@tangle-network/agent-app 0.45.54 → 0.45.55

package/dist/assistant/types.d.ts

@@ -0,0 +1,291 @@
+/**
+ * Wire + UI types for the in-app assistant panel. The wire shapes mirror the
+ * SSE contract emitted by `POST /v1/assistant/chat` (platform-api
+ * `routes/assistant.ts`). Drift here only mis-renders the client; the server
+ * is the source of truth for what it accepts and emits.
+ */
+import type { ReactNode } from "react";
+/** Define delivery modes for assistant interaction as either steering or queue */
+export type AssistantDeliveryMode = "steering" | "queue";
+/** Request body for `POST /api/v1/assistant/chat`. */
+export interface ChatRequest {
+    message: string;
+    /** How to deliver text when a session may already be active. Defaults to steering. */
+    deliveryMode?: AssistantDeliveryMode;
+    /** Model slug to run this turn against; omit to use the server default. */
+    model?: string;
+    /** Omit to start a new thread; pass to continue an existing one. */
+    threadId?: string;
+    /** Per-turn idempotency key — guards against double-charge on retry. */
+    turnKey?: string;
+}
+/** Describe the structure of data representing a thread event with optional model information */
+export interface ThreadEventData {
+    threadId: string;
+    turnId: string;
+    /** The model slug this turn ran against, when the server reports it. */
+    model?: string | null;
+}
+/** Define data structure representing a delta event with associated text content */
+export interface DeltaEventData {
+    text: string;
+}
+/** A chunk of the model's reasoning/thinking, streamed BEFORE the answer for
+ *  reasoning models. Surfaced as a dim "thinking" block so a long reasoning gap
+ *  doesn't read as a frozen panel. Absent for non-reasoning models. */
+export interface ReasoningEventData {
+    text: string;
+}
+/** Emitted when a read-only tool STARTS running, before its result. Lets the
+ *  panel show live "running <tool>…" progress instead of a silent gap. */
+export interface ToolCallEventData {
+    callId: string;
+    name: string;
+    /** The parsed arguments the agent invoked the tool with. Lets a renderer show
+     *  exactly what was called. Omitted by servers predating the field. */
+    args?: Record<string, unknown>;
+}
+/** Describe event data emitted after a tool execution completes with success or error details */
+export interface ToolResultEventData {
+    callId: string;
+    name: string;
+    ok: boolean;
+    output?: unknown;
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+/** What kind of connection a requirement names — drives the card's label and
+ *  connect target. "integration" is an OAuth/api-key connection on the
+ *  integrations page; "github_app" is the GitHub App installed on the repo (the
+ *  event source for a GitHub trigger), connected via the App install flow. */
+export type ConnectionRequirementKind = "integration" | "github_app";
+/** Names one requirement in the same list, by its (provider, kind) identity. */
+export interface ConnectionRequirementRef {
+    provider: string;
+    kind: ConnectionRequirementKind;
+}
+/** A connection a proposed workflow references, and whether the user has it
+ *  connected right now. Surfaced on an authoring proposal so the card can show
+ *  what must be connected — and WHERE — before the workflow can be created. */
+export interface ConnectionRequirement {
+    provider: string;
+    connected: boolean;
+    /** What must be connected. Absent on proposals predating the field — treated
+     *  as "integration" by the card. */
+    kind?: ConnectionRequirementKind;
+    /** Where the user connects this requirement, supplied by the server (the
+     *  GitHub App install URL is deploy config the client can't derive). Null when
+     *  there's no link to offer (e.g. a github_app requirement on a deploy with no
+     *  app slug); the card then shows the requirement without a connect link. */
+    connectUrl?: string | null;
+    /**
+     * Another requirement in the SAME list that must be satisfied before this one
+     * can be, supplied by the server. A GitHub App installation is claimed
+     * through the user's own GitHub OAuth token, so the install is refused while
+     * that connection is missing — the card withholds a connect that could only
+     * end that way, and names the step that comes first instead.
+     *
+     * The server lists a prerequisite BEFORE the requirement naming it. Absent on
+     * proposals predating the field, and on a requirement nothing blocks.
+     */
+    prerequisite?: ConnectionRequirementRef | null;
+}
+/**
+ * Outcome of a host-driven, in-place connect for a single proposal requirement
+ * (see {@link AssistantDockProps.onConnectRequirement}). The host owns the whole
+ * connect experience — an OAuth popup, an api-key entry modal, an app install,
+ * and any error surfacing — and the assistant stays agnostic to how it happens:
+ * the host reports back only whether the requirement is now satisfied, which the
+ * card uses to flip that requirement to connected without a reload. `connected:
+ * false` (a failed or cancelled connect) leaves the card unchanged so the user
+ * can retry.
+ */
+export interface ConnectRequirementResult {
+    connected: boolean;
+}
+/** Describe the data structure for events proposing tool usage with optional integration requirements */
+export interface ToolProposalEventData {
+    /** Null only if the server has no proposal store wired (tools then unusable). */
+    proposalId: string | null;
+    callId: string;
+    name: string;
+    args: unknown;
+    /** Present on a workflow-authoring proposal: the integrations it references
+     *  and their current connection status. Omitted for non-authoring tools. */
+    requirements?: ConnectionRequirement[];
+}
+/** Describe usage event data including tokens, cost, balance, duration, and replay status */
+export interface UsageEventData {
+    promptTokens: number | null;
+    completionTokens: number | null;
+    costUsd: number | null;
+    balanceUsd: number | null;
+    /** Wall-clock duration of the turn in milliseconds, when the server measures
+     *  it. Drives the renderer's tokens/sec figure. Omitted by older servers. */
+    durationMs?: number | null;
+    /** True when a completed turn was replayed from storage (no charge). */
+    replayed?: boolean;
+}
+/** Describe the data emitted when a process turn completes including status and optional flags */
+export interface DoneEventData {
+    turnId: string;
+    status: string;
+    /** True when a mutating tool was proposed and is awaiting confirmation. */
+    proposed?: boolean;
+    /** True when the agentic loop hit its tool-round cap. */
+    capped?: boolean;
+}
+/** Describe error event data including code and message fields */
+export interface ErrorEventData {
+    code: string;
+    message: string;
+}
+/** Discriminated union the stream reader hands to the reducer. */
+export type AssistantStreamEvent = {
+    type: "thread";
+    data: ThreadEventData;
+} | {
+    type: "delta";
+    data: DeltaEventData;
+} | {
+    type: "reasoning";
+    data: ReasoningEventData;
+} | {
+    type: "tool_call";
+    data: ToolCallEventData;
+} | {
+    type: "tool_result";
+    data: ToolResultEventData;
+} | {
+    type: "tool_proposal";
+    data: ToolProposalEventData;
+} | {
+    type: "usage";
+    data: UsageEventData;
+} | {
+    type: "done";
+    data: DoneEventData;
+} | {
+    type: "error";
+    data: ErrorEventData;
+};
+/** A `tool` message is the inline activity chip for a read-only tool the agent
+ *  ran during a turn (e.g. "Validating workflow… ✓"). */
+export type ChatRole = "user" | "assistant" | "status" | "tool";
+/** Live status of a tool-activity chip. */
+export type ToolActivityStatus = "running" | "ok" | "failed";
+/** The outcome of a finished read-only tool, retained on the chip so a renderer
+ *  can show the result body (not just the name + status). Mirrors the
+ *  `tool_result` event: a success carries the tool's `result`; a failure carries
+ *  the error. Absent while the tool is still running. */
+export type ToolOutcome = {
+    ok: true;
+    result?: unknown;
+} | {
+    ok: false;
+    error?: {
+        code: string;
+        message: string;
+    };
+};
+/**
+ * The result of a CONFIRMED mutating tool, retained on the resolving `status`
+ * message so a host can render it prominently (e.g. a one-time API-key reveal).
+ *
+ * SECURITY: `output` may carry a one-time secret (e.g. a freshly minted API
+ * key). It lives ONLY in the in-memory transcript for the session — the message
+ * transcript is deliberately never cached (see `persistence.ts`) and is never
+ * sent back to the model (a turn request carries only the new user text, see
+ * {@link ChatRequest}). So the secret is shown once and is gone on reload,
+ * matching how a dedicated create-key page reveals a key exactly once. A host
+ * renderer must uphold the same contract: reveal-on-demand, never persist it.
+ */
+export interface ConfirmedResult {
+    /** The confirmed tool's name (e.g. "create_api_key"). */
+    name: string;
+    /** The tool's raw output. May contain a one-time secret — see the type doc. */
+    output: unknown;
+    /** The arguments the action was confirmed with, for a renderer that needs them
+     *  (e.g. the key's name). */
+    args?: unknown;
+}
+/** Define the structure and properties of a chat message including optional tool activity details */
+export interface ChatMessage {
+    id: string;
+    role: ChatRole;
+    text: string;
+    /** Present only on `tool` messages — the activity's tool name, the arguments it
+     *  was called with, its state, and (once finished) its outcome. */
+    tool?: {
+        name: string;
+        status: ToolActivityStatus;
+        args?: Record<string, unknown>;
+        outcome?: ToolOutcome;
+    };
+    /** Present only on a `status` message that resolved a confirmed mutating tool
+     *  which returned a renderable result — carries that result so the transcript
+     *  can render a host-supplied card (e.g. a one-time key reveal) next to the
+     *  status line. See {@link ConfirmedResult} for the one-time-secret contract. */
+    result?: ConfirmedResult;
+}
+/** A mutating action the assistant proposed, awaiting the user's confirmation. */
+export interface PendingProposal {
+    proposalId: string | null;
+    callId: string;
+    name: string;
+    args: unknown;
+    /** Integration requirements for a workflow-authoring proposal (each provider
+     *  + whether it's connected); omitted for non-authoring proposals. */
+    requirements?: ConnectionRequirement[];
+    /** Inline error shown ON the card after a RETRYABLE confirm failure (an
+     *  unconnected integration): the card stays so the user can connect and
+     *  confirm again. Null/absent when the card has not failed a retry. */
+    retryError?: string | null;
+}
+/** Describe usage cost, balance, token counts, duration, and replay status for a settled turn */
+export interface UsageInfo {
+    costUsd: number | null;
+    balanceUsd: number | null;
+    /** Token counts + wall-clock duration for the settled turn, when the server
+     *  reports them — drive per-message tokens/sec + cost in a renderer. Optional
+     *  so a consumer constructing this on the prior `{ costUsd, balanceUsd,
+     *  replayed }` shape stays valid; a renderer treats a missing value as null. */
+    promptTokens?: number | null;
+    completionTokens?: number | null;
+    durationMs?: number | null;
+    replayed: boolean;
+}
+/**
+ * The transcript slice handed to a host-supplied `renderTranscript` (see
+ * {@link AssistantPanelProps}). It lets a host swap ONLY the conversation
+ * rendering — to use its own message renderer — while the panel keeps owning the
+ * dock chrome, composer, model picker, history, transport, and proposal
+ * orchestration. The bound `renderProposal` returns the panel's own proposal
+ * card so the host can place it (e.g. inline after the proposing turn) without
+ * re-implementing the confirm/cancel flow.
+ */
+export interface AssistantTranscriptView {
+    messages: ChatMessage[];
+    /** The current turn's reasoning/thinking text, if any (streamed before the
+     *  answer for reasoning models). */
+    reasoning: string | null;
+    /** Id of the assistant message currently accumulating deltas, if any. */
+    streamingId: string | null;
+    /** Model slug the current/most-recent turn ran against, or null. */
+    model: string | null;
+    /** True while a turn is streaming. */
+    isStreaming: boolean;
+    /** True while the agent is working but has produced no visible output yet
+     *  (drives a "thinking" affordance). */
+    isThinking: boolean;
+    pendingProposals: PendingProposal[];
+    /** Cost/tokens/duration for the most recently settled turn, or null before any
+     *  turn settles. Optional so a host predating the field stays a valid consumer;
+     *  a renderer treats a missing value the same as null. */
+    usage?: UsageInfo | null;
+    /** The panel's bound proposal card for a pending proposal — render it where the
+     *  confirm/cancel UI should appear. */
+    renderProposal: (proposal: PendingProposal) => ReactNode;
+}

package/dist/assistant/use-stick-to-bottom.d.ts

@@ -0,0 +1,28 @@
+import { type RefObject } from "react";
+export interface StickToBottomOptions {
+    /** Auto-follow only applies while this is true (e.g. the chat view is shown,
+     *  not the history view). */
+    enabled: boolean;
+    /** A value that changes whenever streamed content grows or the turn's shape
+     *  changes — the trigger to (re-)scroll to the bottom while pinned. */
+    contentSignature: string | number;
+    /** Current streaming turn id (null between turns). A null→id transition
+     *  re-arms follow so a fresh response scrolls from the top. */
+    streamingId: string | null;
+    /** Current thread id (null before any thread loads). A change re-arms follow so
+     *  switching threads lands at the newest content. */
+    threadId: string | null;
+}
+/**
+ * Keep a scroll container pinned to its newest content as it streams, while
+ * yielding the instant the user scrolls up to read. It re-arms when the user
+ * returns to the bottom (via {@link onScroll}) or when a new turn/thread starts.
+ * Returns the `onScroll` handler to attach to the container.
+ *
+ * Extracted from the panel so the follow/yield/re-arm contract is unit-testable
+ * independent of the full component (jsdom doesn't compute scroll geometry, so a
+ * hook test mocks the element's `scrollHeight`/`clientHeight`/`scrollTop`).
+ */
+export declare function useStickToBottom(ref: RefObject<HTMLElement | null>, { enabled, contentSignature, streamingId, threadId }: StickToBottomOptions): {
+    onScroll: () => void;
+};

package/dist/assistant/useAssistantChat.d.ts

@@ -0,0 +1,63 @@
+/**
+ * React binding for the assistant panel: owns the reducer, drives the chat SSE
+ * stream and the proposal-confirmation call, and persists the thread across
+ * reloads. All rendering decisions live in the pure reducer + presentation
+ * helpers; this hook is the glue between them and the network.
+ */
+import { type AssistantState } from "./reducer";
+import type { AssistantDeliveryMode, ConnectionRequirement, ConnectRequirementResult, PendingProposal } from "./types";
+/** Define options for configuring how the assistant sends messages */
+export interface AssistantSendOptions {
+    deliveryMode?: AssistantDeliveryMode;
+}
+/** Host integration callbacks for {@link useAssistantChat}. */
+export interface UseAssistantChatOptions {
+    /**
+     * Called after a workflow-mutating tool (`create_workflow`, `author_workflow`,
+     * …) is confirmed successfully — the host re-fetches its workflow list so the
+     * result appears without a manual reload. Replaces the in-app cross-module
+     * signal the platform used.
+     */
+    onWorkflowMutation?: () => void;
+    /**
+     * Called when the user activates a proposal requirement's connect affordance.
+     * The host runs whatever connect flow it owns — an OAuth popup, an api-key
+     * modal, an app install — and resolves whether the requirement is now
+     * satisfied; the card then flips that requirement to connected. Host-agnostic:
+     * the assistant never learns how the connection is made, so any host (platform,
+     * sandbox, intelligence, …) can supply its own. When omitted, the card falls
+     * back to navigating the requirement's connect target (see
+     * {@link ProposalCardProps.navigate}).
+     */
+    onConnectRequirement?: (requirement: ConnectionRequirement) => Promise<ConnectRequirementResult>;
+}
+/** Define the structure and behavior of an assistant chat session with state, model selection, and message handling */
+export interface AssistantChat {
+    state: AssistantState;
+    /** Proposal ids whose confirmation is currently in flight (for disabling). */
+    confirmingIds: ReadonlySet<string>;
+    /** The user's selected model slug, or null to use the server default. */
+    selectedModel: string | null;
+    /** Choose the model for subsequent turns (persisted per user). */
+    setModel: (model: string | null) => void;
+    send: (message: string, options?: AssistantSendOptions) => void;
+    stop: () => void;
+    confirm: (proposal: PendingProposal) => Promise<void>;
+    cancel: (proposal: PendingProposal) => void;
+    /** True when the host supplied an in-place connect handler
+     *  ({@link UseAssistantChatOptions.onConnectRequirement}); the proposal card
+     *  uses this to offer in-place connect instead of navigating away. */
+    canConnectRequirement: boolean;
+    /** Run the host's in-place connect for one of a proposal's requirements and,
+     *  on success, flip that requirement to connected on the card. Resolves (a
+     *  no-op) when no host handler is set or the connect didn't complete. */
+    connectRequirement: (proposal: PendingProposal, requirement: ConnectionRequirement) => Promise<void>;
+    reset: () => void;
+    /** Open an existing thread from history, loading its transcript. */
+    switchThread: (threadId: string) => void;
+    /** True while a switched-to thread's transcript is loading — the composer is
+     *  held closed until it resolves so a turn can't run against hidden context. */
+    restoring: boolean;
+}
+/** Manage assistant chat state and interactions for a given user ID with optional configurations */
+export declare function useAssistantChat(userId: string | null, options?: UseAssistantChatOptions): AssistantChat;

package/dist/assistant/useAssistantModels.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The assistant's selectable models for the composer's picker. The list is
+ * deployment config (not per-user), so it is fetched once per transport and
+ * shared across panel mounts via a cache keyed by the `AssistantClient`.
+ *
+ * The cache has no TTL: it lives for the page session and is revalidated by a
+ * page refresh — acceptable for deployment-config data that changes only on a
+ * redeploy. An empty/failed fetch is NOT cached, so it retries on the next mount.
+ *
+ * Keyed by client so a host that swaps the transport (a tenant/origin/account
+ * change) never serves the previous client's catalog or skips the fetch for the
+ * new one. A WeakMap lets a discarded client's bucket be collected with it.
+ *
+ * Client-only by design (a `createRoot` SPA, no React SSR), so the cache lives
+ * in one browser tab and is never shared across server requests. Under Strict
+ * Mode's double-mount the two effect runs share the one in-flight fetch; the
+ * first run's `active = false` makes its callback a no-op, the second commits —
+ * dedup holds, no torn state.
+ */
+import type { AssistantModels } from "./client";
+/** Resolve and return the current assistant models from the per-client cache with immediate client swap updates */
+export declare function useAssistantModels(): AssistantModels;

package/dist/assistant/useAssistantThreads.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The user's recent assistant chat threads for the history switcher. Unlike the
+ * model list (deployment config, fetched once), the thread list changes as the
+ * user chats, so it is fetched ON DEMAND — call `refresh()` to (re)load it; the
+ * panel does so when the history view opens and after a turn settles a new
+ * thread into being. It does NOT fetch on mount, so `threads` stays empty and
+ * `loaded` false until the first `refresh()`.
+ *
+ * Self-protective across account AND transport swaps. The list is tagged with the
+ * (user, client) it belongs to and is masked to empty on the SAME commit if that
+ * no longer matches the current props — so a swap never shows the prior scope's
+ * threads for even one frame. In flight, a late result is dropped if either the
+ * user or the client changed, and the request is aborted on the swap.
+ *
+ * A FAILED load is reported, not swallowed. `fetchThreads` answers a non-ok
+ * response, an unusable body or a thrown request with `null`; that used to end
+ * as `loaded: true` over an empty list, which renders identically to a user who
+ * has never chatted. `error` carries the reason so the history view can offer
+ * the retry instead — the `web-react/async` rule (a failed fetch cannot render
+ * as empty data) applied to this hook's own transport.
+ */
+import type { AssistantThreadSummary } from "./client";
+/** Manage and interact with a list of assistant threads including loading, refreshing, and removing threads */
+export interface AssistantThreads {
+    threads: AssistantThreadSummary[];
+    loading: boolean;
+    /** True once a fetch has settled at least once (drives empty-vs-loading copy). */
+    loaded: boolean;
+    /** Why the last load failed, or null. Non-null means the list on hand is stale
+     *  or empty because the request FAILED — never because there is nothing to
+     *  show. Cleared by the next successful load. */
+    error: string | null;
+    /** Load (or reload) the thread list. Must be called to populate `threads` —
+     *  the hook never fetches on mount (the panel calls this when history opens). */
+    refresh: () => void;
+    /** Delete a thread. Optimistically drops it from the list (within the current
+     *  owner scope); on failure the list is reloaded to restore the true state. A
+     *  no-op resolving `{ ok: false }` when the client has no `deleteThread`. */
+    remove: (threadId: string) => Promise<{
+        ok: boolean;
+    }>;
+    /** Whether the configured client supports deletion — drives whether a host
+     *  shows the delete affordance. */
+    canRemove: boolean;
+}
+/** Resolve and manage assistant threads state for a given user including pending deletions and refresh logic */
+export declare function useAssistantThreads(userId: string | null): AssistantThreads;

package/dist/assistant/usePanelPrefs.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Persisted, user-adjustable presentation preferences for the assistant drawer:
+ * its width (drag-to-resize) and a font-size scale. Both survive reloads via
+ * localStorage and are clamped to sane bounds. Kept out of the components so the
+ * SSR-safe persistence and clamping live in one place and stay testable.
+ */
+/** Narrowest the drawer may be dragged — below this the chat is unusable. */
+export declare const MIN_PANEL_WIDTH = 360;
+/** Default drawer width — matches the previous fixed `max-w-md` (28rem). */
+export declare const DEFAULT_PANEL_WIDTH = 448;
+/** Font-size scale bounds and step for the A−/A+ control. 1 = the design
+ *  default; the panel applies this as a CSS `zoom` on the transcript so the
+ *  whole conversation scales uniformly. */
+export declare const MIN_FONT_SCALE = 0.875;
+export declare const MAX_FONT_SCALE = 1.5;
+export declare const DEFAULT_FONT_SCALE = 1;
+interface PanelWidth {
+    /** Current width in px. Apply as an inline `width` only on desktop. */
+    width: number;
+    /** Current max allowed width in px (viewport-derived; updates on resize).
+     *  Exposed for an accurate `aria-valuemax` on the resize control. */
+    maxWidth: number;
+    /** Set an absolute width (clamped + persisted). Use on drag end / discrete
+     *  changes — NOT on every drag tick. */
+    setWidth: (next: number) => void;
+    /** Set an absolute width (clamped, NOT persisted). Use during a live drag so
+     *  the panel tracks the pointer without thrashing localStorage every tick. */
+    previewWidth: (next: number) => void;
+    /** Nudge by a delta (keyboard resize); clamped + persisted. */
+    nudgeWidth: (deltaPx: number) => void;
+}
+/**
+ * The drawer's persisted width. Initialized to the default so first render is
+ * stable; the stored value is read in an effect and applied after mount.
+ * Re-clamps on viewport resize so a stored width can never exceed the current
+ * window, and tracks the live max for the resize control's ARIA bounds.
+ */
+export declare function usePanelWidth(): PanelWidth;
+interface FontScale {
+    scale: number;
+    increase: () => void;
+    decrease: () => void;
+    canIncrease: boolean;
+    canDecrease: boolean;
+}
+/** The panel's persisted font-size scale, with bounded A−/A+ controls. */
+export declare function useFontScale(): FontScale;
+/**
+ * Whether the viewport is at the `md` breakpoint or wider. The drawer is a
+ * full-screen sheet below `md` (no resize), and a width-constrained side panel
+ * at/above it. Defaults to `true` for SSR/first paint — the dialog only renders
+ * after a client interaction, by which point the effect has corrected it.
+ */
+export declare function useIsDesktop(): boolean;
+export {};

package/dist/billing/index.d.ts

@@ -16,7 +16,7 @@
  */
 /** The key-provisioning operations the key manager needs. Wire it from the
  *  platform via {@link createTcloudKeyProvisioner} rather than casting. */
-interface KeyProvisioner {
+export interface KeyProvisioner {
     createKey(input: {
         name: string;
         product: string;
@@ -39,7 +39,7 @@ interface KeyProvisioner {
  * union and whose budgets are `number | null`) is assignable bivariantly. The
  * real SDK client satisfies this; pass it straight in.
  */
-interface TcloudKeyClient {
+export interface TcloudKeyClient {
     createKey(opts: {
         name: string;
         product?: string;
@@ -66,9 +66,9 @@ interface TcloudKeyClient {
  * per-key USD budget, expiry); this maps its shapes (`product` union,
  * `number | null` budgets) onto the manager's contract (`null → undefined`).
  */
-declare function createTcloudKeyProvisioner(client: TcloudKeyClient): KeyProvisioner;
+export declare function createTcloudKeyProvisioner(client: TcloudKeyClient): KeyProvisioner;
 /** A stored child-key record (the app's row, shape-normalized). */
-interface WorkspaceKeyRecord {
+export interface WorkspaceKeyRecord {
     /** App row id (opaque). */
     id: string;
     keyId: string;
@@ -78,7 +78,7 @@ interface WorkspaceKeyRecord {
     expiresAt: Date | null;
 }
 /** Persistence seam — the product implements this against its own D1 table. */
-interface WorkspaceKeyStore {
+export interface WorkspaceKeyStore {
     /** Most-recent active key for the workspace, or null. */
     getActive(workspaceId: string): Promise<WorkspaceKeyRecord | null>;
     /** All active keys (to revoke priors on rotate). */
@@ -98,12 +98,12 @@ interface WorkspaceKeyStore {
     markRevoked(id: string, now: Date): Promise<void>;
 }
 /** Secret encryption seam (the app's at-rest crypto). */
-interface KeyCrypto {
+export interface KeyCrypto {
     encrypt(secret: string): Promise<string>;
     decrypt(encrypted: string): Promise<string>;
 }
 /** Define configuration options for managing workspace keys including provisioning, storage, and cryptography */
-interface WorkspaceKeyManagerOptions {
+export interface WorkspaceKeyManagerOptions {
     provisioner: KeyProvisioner;
     store: WorkspaceKeyStore;
     crypto: KeyCrypto;
@@ -115,7 +115,7 @@ interface WorkspaceKeyManagerOptions {
     product?: string;
 }
 /** Describe usage and budget details for a workspace model key including expiration and exhaustion status */
-interface WorkspaceModelKeyUsage {
+export interface WorkspaceModelKeyUsage {
     keyId: string;
     budgetUsd: number;
     budgetSpent: number;
@@ -124,7 +124,7 @@ interface WorkspaceModelKeyUsage {
     exhausted: boolean;
 }
 /** Manage workspace keys by ensuring, rotating, and tracking usage of active child-key secrets */
-interface WorkspaceKeyManager {
+export interface WorkspaceKeyManager {
     /** The workspace's active child-key secret, provisioning one if absent/expired. */
     ensureKey(workspaceId: string, opts?: {
         budgetUsd?: number;
@@ -141,25 +141,25 @@ interface WorkspaceKeyManager {
     getUsage(workspaceId: string): Promise<WorkspaceModelKeyUsage | null>;
 }
 /** A user's resolved platform identity (from the app's SSO account store). */
-interface PlatformIdentity {
+export interface PlatformIdentity {
     platformUserId: string;
     /** The user's per-user platform API key (reads), or null when unlinked. */
     apiKey: string | null;
 }
 /** Spendable balance for a platform user. */
-interface PlatformBalanceInfo {
+export interface PlatformBalanceInfo {
     balance: number;
     lifetimeSpent: number;
 }
 /** Per-product spend aggregate. */
-interface PlatformProductUsage {
+export interface PlatformProductUsage {
     product: string | null;
     totalSpent: number;
     count: number;
 }
 /** Plan limits — a PARAMETER per product (dollar allowance, concurrency,
  *  overage policy). Never baked into the framework. */
-interface PlanLimit {
+export interface PlanLimit {
     monthlyBalanceUsd: number;
     concurrency: number;
     overageAllowed: boolean;
@@ -170,7 +170,7 @@ interface PlanLimit {
  * the deduct write is a service-token call naming the target user. This module
  * never touches HTTP — it only sequences these calls.
  */
-interface PlatformBillingClient<Plan extends string> {
+export interface PlatformBillingClient<Plan extends string> {
     /** Resolve the user's platform identity, or null when there is no SSO account. */
     resolveIdentity(userId: string): Promise<PlatformIdentity | null>;
     /** Subscription plan for the user (via their platform key). */
@@ -189,7 +189,7 @@ interface PlatformBillingClient<Plan extends string> {
     }): Promise<void>;
 }
 /** Define shared billing state including user ID, plan, balances, concurrency, and overage permission */
-interface SharedBillingState<Plan extends string> {
+export interface SharedBillingState<Plan extends string> {
     /** Platform user id, or null when the user has no Tangle SSO account. */
     platformUserId: string | null;
     plan: Plan;
@@ -200,7 +200,7 @@ interface SharedBillingState<Plan extends string> {
     overageAllowed: boolean;
 }
 /** Define configuration options for managing platform balance based on billing plans */
-interface PlatformBalanceManagerOptions<Plan extends string> {
+export interface PlatformBalanceManagerOptions<Plan extends string> {
     client: PlatformBillingClient<Plan>;
     /** Plan → limits map (the product's pricing). */
     planLimits: Record<Plan, PlanLimit>;
@@ -210,7 +210,7 @@ interface PlatformBalanceManagerOptions<Plan extends string> {
     productSlug: string;
 }
 /** Manage user plans and balances including state retrieval, billing authorization, deduction, and usage tracking */
-interface PlatformBalanceManager<Plan extends string> {
+export interface PlatformBalanceManager<Plan extends string> {
     /** Resolve the user's plan + balance. Unlinked or platform-outage users fail
      *  CLOSED: free plan, zero remaining balance — a billable run is never started
      *  against an unknown balance. */
@@ -236,8 +236,6 @@ interface PlatformBalanceManager<Plan extends string> {
     }>;
 }
 /** Create a platform balance manager to handle user plan limits and state based on provided options */
-declare function createPlatformBalanceManager<Plan extends string>(opts: PlatformBalanceManagerOptions<Plan>): PlatformBalanceManager<Plan>;
+export declare function createPlatformBalanceManager<Plan extends string>(opts: PlatformBalanceManagerOptions<Plan>): PlatformBalanceManager<Plan>;
 /** Create a workspace key manager that handles key provisioning and budget tracking */
-declare function createWorkspaceKeyManager(opts: WorkspaceKeyManagerOptions): WorkspaceKeyManager;
-
-export { type KeyCrypto, type KeyProvisioner, type PlanLimit, type PlatformBalanceInfo, type PlatformBalanceManager, type PlatformBalanceManagerOptions, type PlatformBillingClient, type PlatformIdentity, type PlatformProductUsage, type SharedBillingState, type TcloudKeyClient, type WorkspaceKeyManager, type WorkspaceKeyManagerOptions, type WorkspaceKeyRecord, type WorkspaceKeyStore, type WorkspaceModelKeyUsage, createPlatformBalanceManager, createTcloudKeyProvisioner, createWorkspaceKeyManager };
+export declare function createWorkspaceKeyManager(opts: WorkspaceKeyManagerOptions): WorkspaceKeyManager;