@tangle-network/agent-app 0.45.54 → 0.45.55

package/dist/web/index.d.ts

@@ -1,194 +1,3 @@
-import { K as KvLike } from '../rate-limit-BOVmJRXZ.js';
-export { R as RateLimitResult, c as checkRateLimit } from '../rate-limit-BOVmJRXZ.js';
-
-/**
- * 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())),
- * )
- * ```
- */
-
-/** Requests allowed per identity inside a sliding window. */
-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.
- */
-type FreeRouteClass = 'interactive' | 'compute' | 'heavy';
-/** Default budget per cost class. A product overrides with an explicit
- *  `budget` when it has measured its own route. */
-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. */
-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. */
-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. */
-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.
- */
-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. */
-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. */
-type FreeRouteLimitOutcome = {
-    succeeded: true;
-    value: FreeRouteAllowance;
-} | {
-    succeeded: false;
-    error: FreeRouteLimitError;
-};
-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.
- */
-declare function checkFreeRouteLimit(input: FreeRouteLimitInput): Promise<FreeRouteLimitOutcome>;
-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. */
-declare function freeRouteLimitResponse(error: FreeRouteLimitError, options?: FreeRouteLimitResponseOptions): Response;
-/** The authenticated caller behind one request. */
-interface FreeRouteIdentity {
-    subject: string;
-    workspace?: string | null;
-}
-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).
- */
-declare function withFreeRouteLimit<TArgs>(options: WithFreeRouteLimitOptions<TArgs>, handler: (args: TArgs) => Response | Promise<Response>): (args: TArgs) => Promise<Response>;
-
 /**
  * Web-boundary utilities every agent app's routes hand-roll: JSON body parsing
  * + narrowing, request-context extraction (real client IP behind Cloudflare),
@@ -197,15 +6,16 @@ declare function withFreeRouteLimit<TArgs>(options: WithFreeRouteLimitOptions<TA
  * KV is a structural interface so this needs no `@cloudflare/workers-types`
  * dependency.
  */
-
-type JsonObject = Record<string, unknown>;
+export * from './rate-limit';
+export * from './free-route-limit';
+export type JsonObject = Record<string, unknown>;
 /** Parse + object-narrow a Request body. `[body, null]` on success, `[null,
  *  errorResponse]` on a non-object body (callers `if (err) return err`). */
-declare function parseJsonObjectBody(request: Request): Promise<[JsonObject, null] | [null, Response]>;
+export declare function parseJsonObjectBody(request: Request): Promise<[JsonObject, null] | [null, Response]>;
 /** Narrow one required string field, 400 if missing/empty. */
-declare function requireString(body: JsonObject, field: string): string | Response;
+export declare function requireString(body: JsonObject, field: string): string | Response;
 /** Define the context of a request including IP address, user agent, timestamp, and request ID */
-interface RequestContext {
+export interface RequestContext {
     ipAddress: string;
     userAgent: string;
     timestamp: string;
@@ -213,9 +23,9 @@ interface RequestContext {
 }
 /** Extract request context for audit trails. Uses `CF-Connecting-IP` for the
  *  real client IP behind Cloudflare. */
-declare function extractRequestContext(request: Request): RequestContext;
+export declare function extractRequestContext(request: Request): RequestContext;
 /** Define options for configuring cookie attributes and behavior */
-interface CookieOptions {
+export interface CookieOptions {
     name: string;
     /** Default '/'. */
     path?: string;
@@ -231,13 +41,13 @@ interface CookieOptions {
  *  attributes in Path / HttpOnly / SameSite / Max-Age / Secure order.
  *  Throws on `SameSite=None` without `secure` — browsers silently drop that
  *  combination, which would otherwise fail invisibly. */
-declare function serializeCookie(value: string, opts: CookieOptions): string;
+export declare function serializeCookie(value: string, opts: CookieOptions): string;
 /** Set-Cookie header value that deletes the cookie (empty value, Max-Age=0). */
-declare function clearCookieHeader(opts: Omit<CookieOptions, 'maxAgeSeconds'>): string;
+export declare function clearCookieHeader(opts: Omit<CookieOptions, 'maxAgeSeconds'>): string;
 /** Read + decode one cookie from a Cookie request header; null when absent. */
-declare function readCookieValue(cookieHeader: string | null, name: string): string | null;
+export declare function readCookieValue(cookieHeader: string | null, name: string): string | null;
 /** Define options for configuring security-related HTTP headers including disclaimers and retention labels */
-interface SecurityHeaderOptions {
+export interface SecurityHeaderOptions {
     /** Product disclaimer (e.g. "AI-powered tool. Not legal advice."). Omitted if absent. */
     disclaimer?: string;
     /** Data-retention label (e.g. "7-years"). Omitted if absent. */
@@ -248,7 +58,7 @@ interface SecurityHeaderOptions {
 /** Canonical generic response headers used by {@link addSecurityHeaders}.
  * Exported so static-asset hosts can apply the same policy without copying
  * values that silently drift from Worker/API responses. */
-declare const STANDARD_SECURITY_HEADERS: Readonly<{
+export declare const STANDARD_SECURITY_HEADERS: Readonly<{
     readonly 'Strict-Transport-Security': "max-age=31536000; includeSubDomains; preload";
     readonly 'X-Content-Type-Options': "nosniff";
     readonly 'X-Frame-Options': "SAMEORIGIN";
@@ -258,7 +68,7 @@ declare const STANDARD_SECURITY_HEADERS: Readonly<{
 /** Set standard security headers on a response (HSTS, nosniff, frame-options,
  *  referrer-policy, XSS) + optional product disclaimer/retention. The security
  *  set is generic; the disclaimer/retention are the product's. */
-declare function addSecurityHeaders(response: Response, opts?: SecurityHeaderOptions): Response;
+export declare function addSecurityHeaders(response: Response, opts?: SecurityHeaderOptions): Response;
 /**
  * Canonical media-reference boundary shared by every surface that persists a
  * media url (sequences clips, design-canvas image/video src). The ONE rule:
@@ -270,6 +80,4 @@ declare function addSecurityHeaders(response: Response, opts?: SecurityHeaderOpt
  *
  * @param what - noun for the error message (e.g. 'media url', 'src').
  */
-declare function assertMediaUrl(url: string, what?: string): void;
-
-export { type CookieOptions, FREE_ROUTE_BUDGETS, type FreeRouteAllowance, type FreeRouteClass, type FreeRouteDenialReason, type FreeRouteDimension, type FreeRouteIdentity, FreeRouteLimitError, type FreeRouteLimitInput, type FreeRouteLimitOutcome, type FreeRouteLimitResponseOptions, type JsonObject, KvLike, type RateLimitBudget, type RequestContext, STANDARD_SECURITY_HEADERS, type SecurityHeaderOptions, WORKSPACE_BUDGET_MULTIPLIER, type WithFreeRouteLimitOptions, addSecurityHeaders, assertMediaUrl, checkFreeRouteLimit, clearCookieHeader, extractRequestContext, freeRouteLimitResponse, parseJsonObjectBody, readCookieValue, requireString, serializeCookie, withFreeRouteLimit };
+export declare function assertMediaUrl(url: string, what?: string): void;

package/dist/{rate-limit-BOVmJRXZ.d.ts → web/rate-limit.d.ts}

@@ -5,14 +5,14 @@
  * published surface.
  */
 /** Minimal KV contract (Cloudflare `KVNamespace` satisfies it structurally). */
-interface KvLike {
+export interface KvLike {
     get(key: string): Promise<string | null>;
     put(key: string, value: string, options?: {
         expirationTtl?: number;
     }): Promise<void>;
 }
 /** Describe the outcome of a rate limit check including allowance, remaining count, and reset time */
-interface RateLimitResult {
+export interface RateLimitResult {
     allowed: boolean;
     remaining: number;
     resetAt: number;
@@ -30,6 +30,4 @@ interface RateLimitResult {
  *  truncated value) is treated as a full window, so a tampered key cannot reset
  *  the count and bypass the limiter. A bare `JSON.parse` here would throw and
  *  abort the request handler, silently disabling the limit (fail-open). */
-declare function checkRateLimit(kv: KvLike, key: string, limit: number, windowSeconds: number): Promise<RateLimitResult>;
-
-export { type KvLike as K, type RateLimitResult as R, checkRateLimit as c };
+export declare function checkRateLimit(kv: KvLike, key: string, limit: number, windowSeconds: number): Promise<RateLimitResult>;

package/dist/web-react/agent-session-controls.d.ts

@@ -0,0 +1,105 @@
+/**
+ * `AgentSessionControls` — the CANONICAL model + harness + reasoning-effort
+ * cluster a chat composer docks (see "UI chrome ownership (picker canon)" in
+ * AGENTS.md). One component so every product's two composers (and every
+ * product) share the same control surface and harness↔model coherence policy.
+ *
+ * PICKER CANON. The model menu below IS `/web-react`'s `ModelPicker` and the
+ * thinking-budget pill IS `EffortPicker` — the canonical ecosystem pickers.
+ * sandbox-ui's `dashboard/ModelPicker` and the model menu inside sandbox-ui's
+ * `chat/AgentSessionControls` are legacy (deprecated, frozen, removed at
+ * sandbox-ui's next major), and the `/chat-react` `ComposerAgentControls`
+ * adapter that rendered sandbox-ui's strip is REMOVED — a surface that still
+ * renders the sandbox-ui strip is showing the old design; migrate it
+ * (props mapping in `docs/ui-picker-canon.md`).
+ *
+ * Dependency-free beyond React by design: `/web-react` must not force the
+ * optional sandbox-ui peer, so this component — the canonical one — can never
+ * require it.
+ *
+ * Two layouts, additive — the default preserves the prior hand-rolled behavior:
+ *  - `layout="inline"` (default): model, harness, and effort sit side by side as
+ *    pills. This is the original arrangement; existing call sites that mounted
+ *    `ModelPicker` + a harness picker + `EffortPicker` in a row get the same UI.
+ *  - `layout="compact"`: the model picker stays inline and visible; the agent
+ *    backend ("harness") and reasoning-effort controls — internal jargon a user
+ *    rarely needs — tuck behind a single gear popover with plain-English copy.
+ *
+ * Harness ↔ model coherence is identical in both layouts, via the substrate's
+ * snap helpers (`@tangle-network/agent-app/harness`): changing the harness snaps
+ * an incompatible model to that harness's best catalog option; changing the
+ * model switches to the model's native harness. Catalog model ids are canonical
+ * ("provider/model"), which is exactly what the snap helpers expect — no id
+ * translation is needed here.
+ *
+ * Dependency-free beyond React: inline SVG glyphs, CSS-var / Tailwind tokens the
+ * app shell defines. The harness picker is rendered inline so this needs no
+ * sandbox-ui dependency.
+ */
+import { type ReactNode } from 'react';
+import { type Harness } from '../harness';
+import type { CatalogModel } from '../runtime/model-catalog';
+import type { EffortLevel } from './controls';
+export interface AgentSessionControlsProps {
+    /** Catalog models — canonical provider-prefixed ids. */
+    models: CatalogModel[];
+    modelsLoading?: boolean;
+    /** Selected canonical model id. */
+    model: string;
+    onModelChange(modelId: string): void;
+    /** Current harness; harness↔model coherence is enforced on every change. */
+    harness: Harness;
+    onHarnessChange(harness: Harness): void;
+    /** Harnesses to offer; defaults to the labeled set. */
+    availableHarnesses?: ReadonlyArray<Harness>;
+    /** Reasoning-effort value + setter. Shown only when the selected model
+     *  `supportsReasoning`, matching `EffortPicker`'s guidance. */
+    effort: string;
+    onEffortChange(effort: string): void;
+    /**
+     * Levels to offer, forwarded verbatim to {@link EffortPicker}. Omit for the
+     * default vocabulary.
+     *
+     * A product whose backend applies only a SUBSET of the levels for the
+     * selected harness/model passes that subset here. Without it the strip
+     * offers every level and the backend silently ignores the ones it does not
+     * apply — a control that reports a choice the system never made.
+     *
+     * This is the COMPLETE renderable set, not an allow-list layered over a
+     * default one — the removed `ComposerAgentControls`' `available` list was the
+     * latter, and its picker injected the `auto` sentinel itself. A list that
+     * omits the current {@link effort} is still safe: `EffortPicker` reconciles
+     * the selected value into the rendered list under its own name rather than
+     * resolving it to a different entry (`reconcileEffortLevels`). Build the list
+     * from engine ids with `effortLevelsFromIds`; the migration is in
+     * `docs/ui-picker-canon.md`.
+     */
+    effortLevels?: readonly EffortLevel[];
+    /**
+     * `inline` (default): model, harness, effort side by side — the prior
+     * behavior. `compact`: model inline, harness + effort behind a gear popover.
+     */
+    layout?: 'inline' | 'compact';
+    /** Hide the harness control entirely (single-harness products). */
+    showHarness?: boolean;
+    /**
+     * PIN the harness and say why, in the user's words ("This thread already has
+     * messages — start a new chat to switch backend"). Presence IS the lock:
+     * there is no separate boolean, because a lock a user cannot read is the
+     * thing this prop exists to replace.
+     *
+     * The control stays VISIBLE and reports the harness the thread is on — the
+     * shape a locked selector has to keep, since a thread whose backend is fixed
+     * is exactly when a user wants to know what it is. Hiding it (`showHarness:
+     * false`) is what pushed products into rendering their own lock label
+     * outside the panel.
+     *
+     * While locked, `onHarnessChange` is never called — not from the picker, and
+     * not from the model↔harness coherence policy either. See
+     * {@link useCoherentHandlers}.
+     */
+    harnessLockReason?: string;
+    renderProviderBadge?: (provider: string) => ReactNode;
+    className?: string;
+}
+export declare function AgentSessionControls(props: AgentSessionControlsProps): import("react").JSX.Element;

package/dist/web-react/async/async-view.d.ts

@@ -0,0 +1,69 @@
+import { type ReactElement, type ReactNode } from 'react';
+import type { AsyncResourceState } from './state';
+import type { MutationState } from './use-confirmed-mutation';
+export interface AsyncEmptyAction {
+    label: string;
+    onClick: () => void;
+}
+export interface AsyncEmptySpec {
+    /** What is not there, in the reader's words ("No templates yet"). Required:
+     *  an empty state with nothing to say is the state this module exists to
+     *  stop being mistaken for a failure. */
+    title: string;
+    description?: string;
+    /** The next action. An element is rendered as supplied (a link, a dialog
+     *  trigger); the object form renders the standard button. */
+    action?: AsyncEmptyAction | ReactElement;
+}
+export interface AsyncErrorRenderProps {
+    message: string;
+    retry: () => void;
+}
+export interface AsyncViewProps<T> {
+    state: AsyncResourceState<T>;
+    /** Rendered only for `ready`, with the loaded value — the branch cannot be
+     *  entered without one. */
+    children: (value: T) => ReactNode;
+    /** Required: `empty` must name what is missing and what to do about it. */
+    empty: AsyncEmptySpec | ReactElement;
+    /** Must return an element. Returning nothing is what produced the blank
+     *  screens this component replaces, so a nullish return falls back to the
+     *  built-in block rather than rendering nothing. */
+    renderLoading?: () => ReactElement;
+    renderError?: (props: AsyncErrorRenderProps) => ReactElement;
+    /** `idle` renders the loading block by default — from the reader's side,
+     *  "not started" and "in flight" are the same wait. */
+    renderIdle?: () => ReactElement;
+    loadingLabel?: string;
+    retryLabel?: string;
+    /** Applied to the wrapper around the non-`ready` branches. `ready` renders the
+     *  children with no wrapper element, so grids and lists keep their layout. */
+    className?: string;
+}
+/**
+ * Renders the branch the state is actually in.
+ *
+ * The three anti-patterns this replaces (`catch` that only clears a loading
+ * flag, early return on a non-ok response, bare `null` while loading) all end at
+ * the same rendered output as a successful-but-empty load. Here every branch is
+ * reached from a different variant and each renders visibly: `loading` and
+ * `idle` render a labelled busy block, `error` renders the message plus the
+ * retry, `empty` renders the caller's copy and next action, and `ready` is the
+ * only branch with a value to hand to `children`.
+ */
+export declare function AsyncView<T>({ state, children, empty, renderLoading, renderError, renderIdle, loadingLabel, retryLabel, className, }: AsyncViewProps<T>): ReactElement;
+export interface MutationStatusLabels {
+    pending?: string;
+    succeeded?: string;
+}
+export interface MutationStatusProps<T> {
+    state: MutationState<T>;
+    labels?: MutationStatusLabels;
+    className?: string;
+}
+/**
+ * The write's own status line. "Saved" renders only from `succeeded`, which
+ * `useConfirmedMutation` can only reach through a confirmed write, so the label
+ * cannot appear over a failed request.
+ */
+export declare function MutationStatus<T>({ state, labels, className }: MutationStatusProps<T>): ReactElement | null;