@lunora/svelte 1.0.0-alpha.30 → 1.0.0-alpha.300

package/dist/index.d.mts

@@ -1,171 +1,822 @@
-import { LunoraClient, User, ConnectionStatus, Preloaded, FunctionReference, ReturnOf, ArgsOf, MutationCallOptions, MutatorHandle, SubscriptionErrorCallback } from '@lunora/client';
+import { FunctionReference, ArgsOf, ActionCallOptions, ReturnOf, LunoraClient, SubscriptionErrorCallback, User, ConnectionStatus, Preloaded, LiveStreamSubscribeError, LiveTopicRef, LiveTopicOptions, MutationCallOptions, OnlineOnlyOption, MutatorHandle, SubscriptionError } from '@lunora/client';
 export type { ArgsOf, ConnectionStatus, FunctionReference, LunoraClient, MutationCallOptions, MutatorHandle, MutatorTransaction, Preloaded, ReturnOf } from '@lunora/client';
 import { Readable } from 'svelte/store';
+import { AuthStatus } from '@lunora/client/auth';
 import { PaginationStatus } from '@lunora/client/pagination';
 import { RateLimitStatus, RateLimitConfig } from '@lunora/ratelimit';
 /**
-* Publish a {@link LunoraClient} on the Svelte component context so that
-* descendant components can read it with {@link getLunoraClient} (or implicitly,
-* via the default-client lookups inside `query`/`mutation`/`hydratePreloaded`).
-*
-* Call this once, high in the tree (typically your root `+layout.svelte` or
-* `App.svelte`), during component initialisation — `setContext` must run while
-* the component is being constructed, exactly like React's provider mounts once.
-* This is the Svelte analogue of mounting `LunoraProvider`.
-*/
+ * The reactive handle returned by {@link action} — the Svelte counterpart to
+ * React's `useAction`, re-expressed as stores you read with `$`. The surface is
+ * identical across the Lunora adapters (`@lunora/solid`, `/vue`).
+ */
+interface ActionHandle<F extends FunctionReference> {
+  /**
+   * Run the action. Resolves with the server result and rejects on failure
+   * (errors propagate — there is no swallowing).
+   */
+  call: (args: ArgsOf<F>, options?: ActionCallOptions) => Promise<ReturnOf<F>>;
+  /** The latest invocation's resolved value, or `undefined` before the first success. */
+  data: Readable<ReturnOf<F> | undefined>;
+  /** The latest invocation's error, or `undefined`. */
+  error: Readable<Error | undefined>;
+  /**
+   * `true` while any invocation from this handle is in flight. Ref-counted, so
+   * overlapping calls compose and it only flips back to `false` once the last
+   * one settles. Read it with `$pending` in a component to disable a button.
+   */
+  pending: Readable<boolean>;
+  /** Clear `data`/`error` back to idle. */
+  reset: () => void;
+}
+/**
+ * Create an {@link ActionHandle} for an action reference. The Svelte
+ * counterpart to React's `useAction`: returns `{ data, error, pending, call,
+ * reset }` of readable stores plus an awaitable `call`.
+ *
+ * **Narrower than `mutation` on purpose:** no `optimistic` /
+ * `optimisticUpdate`. An optimistic update patches the subscription cache on the
+ * assumption a write will land; an action is not a write — it runs in the
+ * Worker, may call a third party, and has no declared effect on any query.
+ *
+ * `data`/`error` follow the adapter-wide contract: both track the LATEST
+ * invocation (an earlier call settling later cannot clobber a newer one), a
+ * success clears `error`, and a failure leaves the previous `data` in place.
+ * `reset()` clears both; it does not cancel an in-flight call.
+ *
+ * Pass `client` explicitly, or omit it to resolve the ambient client published
+ * by `setLunoraClient`.
+ */
+declare function action<F extends FunctionReference>(function_: F): ActionHandle<F>;
+declare function action<F extends FunctionReference>(client: LunoraClient, function_: F): ActionHandle<F>;
+/**
+ * The lifecycle status stored on an agent thread. Client-safe mirror of
+ * `@lunora/agent`'s `AgentThreadStatus` — re-declared here (rather than imported)
+ * so this Svelte entry never pulls in the server-only `@lunora/agent` module graph
+ * (the adapter stays Svelte + `@lunora/client` only). Keep in sync with
+ * `packages/agent/src/types.ts`.
+ */
+type AgentThreadStatus = "awaiting_input" | "cancelled" | "error" | "idle" | "running";
+/**
+ * The live thread record surfaced by the `agents:agentThread` query. A structural
+ * subset of the persisted thread row — every field beyond `status` is optional so
+ * the shape stays forgiving as the server schema grows. Keep in sync with the
+ * `agent_threads` table in `packages/agent/src/component.ts`.
+ */
+interface AgentThreadRecord {
+  createdAt?: number;
+  /**
+   * The failure message when `status === "error"`, `null` once a later run
+   * cleared it, absent on a thread that has never failed. Read it for
+   * truthiness — `null` and absent both mean "no error".
+   */
+  error?: null | string;
+  /** The workflow instance id of the in-flight run — the handle `cancel` targets. */
+  instanceId?: string;
+  messageCount?: number;
+  /** The verified thread owner, when the run was started with one. */
+  owner?: string;
+  status: AgentThreadStatus;
+  title?: string;
+  updatedAt?: number;
+}
+/**
+ * The `agents.agentThread` reference the handle subscribes to for live thread
+ * state (status + the in-flight `instanceId`). A structural subset of the
+ * generated `api.agents` surface, so the whole generated `api` object is
+ * assignable.
+ */
+interface AgentApi {
+  agents: {
+    agentThread: FunctionReference<"query", {
+      key: string;
+    }, Record<string, unknown> | undefined>;
+  };
+}
+interface AgentOptions {
+  /** The generated `api` — its `agents.agentThread` query drives live thread state. */
+  api: AgentApi;
+  /**
+   * Optional app mutation over the agent's cancel path
+   * (`ctx.agents[name].cancel(id)`). Called with `{ instanceId, threadKey }`.
+   * When omitted (or no run is in flight) {@link AgentHandle.cancel} is a no-op.
+   */
+  cancel?: FunctionReference<"mutation">;
+  /**
+   * Called when the live thread subscription reports an error (a session
+   * expiry, an RLS denial). Without it such an error is dropped and `thread` /
+   * `status` freeze at their last value — unlike the React, Angular, Solid and Vue
+   * ports, this one leaves the value store untouched on error.
+   */
+  onError?: SubscriptionErrorCallback;
+  /**
+   * The app mutation that starts (or continues) a run — a thin wrapper over
+   * `ctx.agents[name].run(...)`. Called with `{ threadKey, input }` merged with
+   * {@link AgentOptions.runArgs} and the per-call args.
+   */
+  run: FunctionReference<"mutation">;
+  /** Extra args merged into every `run` call (e.g. an `owner` or `title`). */
+  runArgs?: Record<string, unknown>;
+  /** The thread to observe and drive. */
+  threadKey: string;
+}
+interface AgentHandle {
+  /**
+   * Terminate the in-flight run and mark its thread `"cancelled"`. Resolves as a
+   * no-op when no `cancel` mutation was supplied or no run is in flight.
+   */
+  cancel: () => Promise<void>;
+  /** `true` while a `run` invocation is in flight. Read with `$pending`. */
+  pending: Readable<boolean>;
+  /** Start (or continue) a run with a user message; extra args merge over `runArgs`. */
+  run: (input: string, args?: Record<string, unknown>) => Promise<void>;
+  /** The live thread status, or `undefined` before the thread exists. Read with `$status`. */
+  status: Readable<AgentThreadStatus | undefined>;
+  /**
+   * Stop the live thread subscription. Call in `onDestroy`
+   * (`onDestroy(handle.teardown)`).
+   */
+  teardown: () => void;
+  /** The live thread record (status, `instanceId`, …), or `undefined` before it exists. Read with `$thread`. */
+  thread: Readable<AgentThreadRecord | undefined>;
+}
+/**
+ * A thin agent handle: live thread `status` plus `run` / `cancel`, without the
+ * chat message surface — the Svelte counterpart to React's `useAgent`,
+ * re-expressed as stores you read with `$`. Composes `client.subscribe` for live
+ * thread state and {@link mutation} for the run/cancel writes. For the full
+ * conversation surface (durable history + approvals) use `agentChat`.
+ *
+ * `run` and `cancel` stay generic over the app-defined mutations that wrap
+ * `ctx.agents[name].run` / `.cancel`, so the handle hard-codes no function names
+ * beyond the `agents:*` surface. The subscription opens eagerly on the call and
+ * runs until {@link AgentHandle.teardown} — call `onDestroy(handle.teardown)`.
+ *
+ * Pass `client` explicitly, or omit it to resolve the ambient client published by
+ * `setLunoraClient`.
+ */
+declare function agent(options: AgentOptions): AgentHandle;
+declare function agent(client: LunoraClient, options: AgentOptions): AgentHandle;
+/**
+ * One persisted (or optimistic) thread message, as `agents:agentMessages`
+ * surfaces it. Client-safe mirror of `@lunora/agent`'s `AgentMessageRow` —
+ * re-declared here (rather than imported) so this Svelte entry never pulls in the
+ * server-only `@lunora/agent` module graph. Keep in sync with the
+ * `agent_messages` table in `packages/agent/src/component.ts`.
+ */
+interface AgentChatMessage {
+  content: string;
+  createdAt?: number;
+  /**
+   * `true` for a client-side optimistic user message not yet acknowledged by
+   * the server. Cleared once the durable history carries the matching user turn.
+   */
+  optimistic?: boolean;
+  role: "assistant" | "system" | "tool" | "user";
+  seq: number;
+  /** Approval or secret-request lifecycle marker on a human-in-the-loop tool message. */
+  status?: "approved" | "awaiting_approval" | "awaiting_secret" | "rejected";
+  toolCallId?: string;
+  toolCalls?: ReadonlyArray<{
+    id: string;
+    input: unknown;
+    name: string;
+  }>;
+  toolName?: string;
+}
+/**
+ * A live token delta streamed while a turn is generating. Client-safe mirror of
+ * `@lunora/agent`'s `AgentTokenDelta`. Ephemeral — deltas feed
+ * {@link AgentChatHandle.streamingText} live and are never replayed; the
+ * persisted assistant message stays the single source of truth.
+ */
+interface AgentTokenDelta {
+  /** Discriminates the token arm of {@link AgentLiveEvent}; unset on the wire (token is the default). */
+  kind?: "token";
+  /** The incremental text chunk the model just produced. */
+  text: string;
+  /** The thread this delta belongs to. */
+  threadKey: string;
+  /** The zero-based index of the turn producing the delta. */
+  turn: number;
+}
+/**
+ * A live tool-progress event streamed via `ctx.reportProgress(...)`. Client-safe
+ * mirror of `@lunora/agent`'s `AgentProgressEvent`. Ephemeral and `toolCallId`-keyed;
+ * surfaced by `agentToolEvents`, ignored by {@link AgentChatHandle.streamingText}.
+ */
+interface AgentProgressEvent {
+  /** The arbitrary, JSON-serializable payload the tool reported. */
+  data: unknown;
+  /** Discriminates the progress arm of {@link AgentLiveEvent}. */
+  kind: "progress";
+  /** The thread this event belongs to. */
+  threadKey: string;
+  /** The tool call this progress belongs to. */
+  toolCallId: string;
+}
+/**
+ * A single event on the agent's live-only channel — a streamed token delta or a
+ * tool progress event. Client-safe mirror of `@lunora/agent`'s `AgentLiveEvent`.
+ * Discriminate on `kind` (`"progress"` for the progress arm; token deltas leave
+ * it unset).
+ */
+type AgentLiveEvent = AgentProgressEvent | AgentTokenDelta;
+/** The `agents:agentMessages` reference — live durable thread history. */
+type AgentMessagesReference$1 = FunctionReference<"query", {
+  key: string;
+  limit?: number;
+}, ReadonlyArray<Record<string, unknown>>>;
+/** The `agents:agentResolveApproval` reference — resolves a human-in-the-loop tool approval. */
+type AgentApprovalReference = FunctionReference<"mutation", {
+  decision: "approve" | "approve_for_thread" | "reject";
+  instanceId: string;
+  note?: string;
+  threadKey: string;
+  toolCallId: string;
+}, {
+  resolved: boolean;
+}>;
+/** The `agents:agentSupplySecret` reference — stores a person's value for a paused `requestSecretTool` call. */
+type AgentSupplySecretReference = FunctionReference<"mutation", {
+  secret: string;
+  threadKey: string;
+  toolCallId: string;
+}, {
+  resolved: boolean;
+}>;
+/** The `agents:agentDeclineSecret` reference — refuses a paused `requestSecretTool` call. */
+type AgentDeclineSecretReference = FunctionReference<"mutation", {
+  threadKey: string;
+  toolCallId: string;
+}, {
+  resolved: boolean;
+}>;
+/** The `agents:agentThread` reference — live thread status + in-flight `instanceId`. */
+type AgentThreadReference = FunctionReference<"query", {
+  key: string;
+}, Record<string, unknown> | undefined>;
+/** A tool approved for the rest of a thread, as `agents:agentApprovalGrants` lists it. */
+interface AgentApprovalGrant {
+  createdAt: number;
+  toolName: string;
+}
+/** The `agents:agentApprovalGrants` reference — live thread-scoped approval grants. */
+type AgentApprovalGrantsReference = FunctionReference<"query", {
+  key: string;
+}, ReadonlyArray<AgentApprovalGrant>>;
+/** The `agents:agentRevokeApprovalGrant` reference — removes a thread-scoped approval grant. */
+type AgentRevokeApprovalGrantReference = FunctionReference<"mutation", {
+  threadKey: string;
+  toolName: string;
+}, {
+  revoked: boolean;
+}>;
+/**
+ * An app stream reference that tees the agent's in-flight live events, keyed by
+ * thread. Carries token deltas and — since `ctx.reportProgress` rides the same
+ * sink — tool progress events; this handle consumes only the token arm.
+ */
+type AgentTokenStreamReference = FunctionReference<"stream", {
+  key: string;
+}, AgentLiveEvent>;
+/**
+ * The `agents.*` reference surface the chat handle reads. A structural subset of
+ * the generated `api.agents`, so the whole generated `api` object is assignable.
+ */
+interface AgentChatApi {
+  agents: {
+    agentApprovalGrants: AgentApprovalGrantsReference;
+    agentDeclineSecret: AgentDeclineSecretReference;
+    agentMessages: AgentMessagesReference$1;
+    agentResolveApproval: AgentApprovalReference;
+    agentRevokeApprovalGrant: AgentRevokeApprovalGrantReference;
+    agentSupplySecret: AgentSupplySecretReference;
+    agentThread: AgentThreadReference;
+  };
+}
+interface AgentChatOptions {
+  /** The generated `api` — its `agents.*` surface provides history, thread state, and approval resolution. */
+  api: AgentChatApi;
+  /**
+   * Optional app mutation over the agent's cancel path
+   * (`ctx.agents[name].cancel(id)`). Called with `{ instanceId, threadKey }`.
+   * When omitted (or no run is in flight) {@link AgentChatHandle.cancel} is a
+   * no-op.
+   */
+  cancel?: FunctionReference<"mutation">;
+  /** History depth forwarded to `agents:agentMessages`. */
+  limit?: number;
+  /**
+   * Called when the live history, thread, or grants subscription reports an error (a
+   * session expiry, an RLS denial). Without it such an error is dropped and
+   * `messages` / `status` freeze at their last value — unlike the React, Angular,
+   * Solid and Vue ports, this one leaves the value store untouched on error.
+   */
+  onError?: SubscriptionErrorCallback;
+  /**
+   * The app mutation that starts (or continues) a run — a thin wrapper over
+   * `ctx.agents[name].run(...)`. Called with `{ threadKey, input }` merged with
+   * {@link AgentChatOptions.sendArgs} and the per-call args.
+   */
+  send: FunctionReference<"mutation">;
+  /** Extra args merged into every `send` call (e.g. an `owner` or `title`). */
+  sendArgs?: Record<string, unknown>;
+  /**
+   * Optional live token-delta stream — an app stream function that tees the
+   * agent's in-flight deltas. When omitted {@link AgentChatHandle.streamingText}
+   * stays empty and the UI updates message-by-message from durable history.
+   */
+  stream?: AgentTokenStreamReference;
+  /** The thread to observe and continue. */
+  threadKey: string;
+}
+interface AgentChatHandle {
+  /** The tools approved for the rest of this thread, live. Read with `$approvalGrants`. */
+  approvalGrants: Readable<ReadonlyArray<AgentApprovalGrant>>;
+  /** Approve a paused human-in-the-loop tool call (optionally with a note). */
+  approve: (toolCallId: string, note?: string) => Promise<void>;
+  /**
+   * Approve a paused tool call and grant that tool for the rest of the thread, so
+   * later calls to it run without pausing. Undo with {@link AgentChatHandle.revokeGrant}.
+   */
+  approveForThread: (toolCallId: string, note?: string) => Promise<void>;
+  /**
+   * Terminate the in-flight run and mark its thread `"cancelled"`. Resolves as a
+   * no-op when no `cancel` mutation was supplied or no run is in flight.
+   */
+  cancel: () => Promise<void>;
+  /** Refuse a paused `requestSecretTool` call: the run resumes with a "declined" result. */
+  declineSecret: (toolCallId: string) => Promise<void>;
+  /** Durable thread history (oldest first) plus any un-acknowledged optimistic user turns. Read with `$messages`. */
+  messages: Readable<ReadonlyArray<AgentChatMessage>>;
+  /** Reject a paused human-in-the-loop tool call (optionally with a reason). */
+  reject: (toolCallId: string, note?: string) => Promise<void>;
+  /** Remove a thread-scoped approval grant so the tool's gate applies again to later calls. */
+  revokeGrant: (toolName: string) => Promise<void>;
+  /** Start (or continue) a run with a user message; extra args merge over `sendArgs`. Appends an optimistic user turn. */
+  send: (input: string, args?: Record<string, unknown>) => Promise<void>;
+  /** The live thread status, or `undefined` before the thread exists. Read with `$status`. */
+  status: Readable<AgentThreadStatus | undefined>;
+  /**
+   * The in-flight turn's streamed text — live-only, `""` once the turn persists
+   * to `messages`. Populated when a `stream` reference is supplied (via the
+   * {@link stream} primitive); with no reference it stays `""` and the UI advances
+   * message-by-message from durable history. Read with `$streamingText`.
+   */
+  streamingText: Readable<string>;
+  /**
+   * Give a paused `requestSecretTool` call its value. Always sent online-only: the
+   * value is never queued, persisted or replayed, and the call rejects with
+   * `OFFLINE_NOT_QUEUED` while the connection is down. The handle keeps no copy;
+   * a failure rethrows the original error.
+   */
+  supplySecret: (toolCallId: string, secret: string) => Promise<void>;
+  /**
+   * Stop the live history, thread, and grants subscriptions (and the token stream, if any).
+   * Call in `onDestroy` (`onDestroy(handle.teardown)`).
+   */
+  teardown: () => void;
+}
+/**
+ * A first-class agent chat surface: live durable history + in-flight token
+ * streaming + the send / approve / reject / secret / cancel writes, keyed by `threadKey` —
+ * the Svelte counterpart to React's `useAgentChat`, re-expressed as stores you
+ * read with `$`.
+ *
+ * It composes the existing primitives rather than adding transport:
+ * `client.subscribe(api.agents.agentMessages)` for durable history,
+ * `client.subscribe(api.agents.agentThread)` for live status + the in-flight
+ * `instanceId`, {@link stream} over an app token stream for in-flight deltas, and
+ * {@link mutation} for the writes (`api.agents.agentResolveApproval` for approvals;
+ * app-defined wrappers for `send`/`cancel`). Only the `agents:*` surface is
+ * hard-coded — `send`/`cancel`/`stream` stay generic references.
+ *
+ * A `send` optimistically appends the user turn so it renders immediately; the
+ * optimistic row clears once the durable history carries the acknowledged turn.
+ * `streamingText` is live-only: it holds the current turn's streamed text and
+ * empties as soon as that turn's assistant message lands in `messages` (the
+ * persisted message is the source of truth); with no `stream` reference it stays
+ * `""` and the UI advances message-by-message from durable history. The
+ * subscriptions (and the token stream, if any) open eagerly and run until
+ * {@link AgentChatHandle.teardown} — call `onDestroy(handle.teardown)`.
+ *
+ * Pass `client` explicitly, or omit it to resolve the ambient client published by
+ * `setLunoraClient`.
+ */
+declare function agentChat(options: AgentChatOptions): AgentChatHandle;
+declare function agentChat(client: LunoraClient, options: AgentChatOptions): AgentChatHandle;
+/**
+ * The `agents.agentState` reference the handle subscribes to for the thread's live
+ * synced state. A structural subset of the generated `api.agents` surface (like
+ * `AgentApi` for `agentThread`), so the whole generated `api` object is
+ * assignable. Client-safe: no `@lunora/agent` import — the per-agent state type is
+ * mirrored by the handle's generic `T`, since codegen pins the reference return as
+ * an optional record (it never evaluates agent config).
+ */
+interface AgentStateApi {
+  agents: {
+    agentState: FunctionReference<"query", {
+      key: string;
+    }, Record<string, unknown> | undefined>;
+  };
+}
+interface AgentStateOptions {
+  /** The generated `api` — its `agents.agentState` query drives live thread state. */
+  api: AgentStateApi;
+  /** The thread whose synced state to observe. */
+  threadKey: string;
+}
+interface AgentStateHandle<T> {
+  /** Svelte readable store of the subscription error, if the live channel reported one. Read with `$error`. */
+  error: Readable<Error | undefined>;
+  /** Svelte readable store of the live synced state, or `undefined` before it is seeded/first pushed. Read with `$state`. */
+  state: Readable<T | undefined>;
+}
+/**
+ * Subscribe to an agent thread's synced state — the `setState`-style value a tool
+ * writes with `ctx.setState(...)`, seeded by `defineAgent({ initialState })`. A
+ * thin wrapper over {@link subscription} against `api.agents.agentState`: the
+ * server pushes a fresh frame whenever the state changes (the dedicated query's
+ * per-socket JSON memo suppresses no-op pushes on unrelated thread writes), so
+ * `state` updates only on a real `setState`. The Svelte counterpart to React's
+ * `useAgentState`, re-expressed as stores you read with `$`.
+ *
+ * Generic over the app's state shape (`agentState<SupportState>(...)`, itself a
+ * record) — the reference is typed as an optional record because codegen cannot
+ * see the per-agent state type; the generic casts to `T`. The `state`/`error`
+ * stores are lazy, so the subscription opens on the first subscriber to `state`
+ * and tears down when the last one leaves — there is no `teardown` to call.
+ *
+ * Pass `client` explicitly, or omit it to resolve the ambient client published by
+ * `setLunoraClient`.
+ */
+declare function agentState<T extends Record<string, unknown> = Record<string, unknown>>(options: AgentStateOptions): AgentStateHandle<T>;
+declare function agentState<T extends Record<string, unknown> = Record<string, unknown>>(client: LunoraClient, options: AgentStateOptions): AgentStateHandle<T>;
+/** The `agents:agentMessages` reference — live durable thread history. */
+type AgentMessagesReference = FunctionReference<"query", {
+  key: string;
+  limit?: number;
+}, ReadonlyArray<Record<string, unknown>>>;
+/**
+ * An app stream reference that tees the agent's in-flight live events, keyed by
+ * thread. Carries token deltas and tool progress events; this handle consumes only
+ * the progress arm (`kind === "progress"`).
+ */
+type AgentLiveStreamReference = FunctionReference<"stream", {
+  key: string;
+}, AgentLiveEvent>;
+/**
+ * The `agents.*` reference surface the tool-events handle reads. A structural
+ * subset of the generated `api.agents`, so the whole generated `api` object is
+ * assignable.
+ */
+interface AgentToolEventsApi {
+  agents: {
+    agentMessages: AgentMessagesReference;
+  };
+}
+interface AgentToolEventsOptions {
+  /** The generated `api` — its `agents.agentMessages` query provides the durable tool lifecycle. */
+  api: AgentToolEventsApi;
+  /** History depth forwarded to `agents:agentMessages`. */
+  limit?: number;
+  /**
+   * Optional live event stream — the same app stream function `agentChat` uses.
+   * When supplied, ephemeral `ctx.reportProgress(...)` events for the thread are
+   * surfaced as `{ type: "progress" }` entries; when omitted only the durable
+   * lifecycle (call / result / awaiting-approval / awaiting-secret) is returned.
+   */
+  stream?: AgentLiveStreamReference;
+  /** The thread whose tool activity to observe. */
+  threadKey: string;
+}
+/**
+ * A single tool-lifecycle event for a thread. The durable arms
+ * (`call`/`result`/`awaiting-approval`/`awaiting-secret`) are derived from `agents:agentMessages`
+ * and carry the persisted `seq`; the ephemeral `progress` arm comes live off the
+ * stream and has no `seq`. Discriminate on `type`.
+ */
+type AgentToolEvent = {
+  data: unknown;
+  toolCallId: string;
+  type: "progress";
+} | {
+  input: unknown;
+  seq: number;
+  toolCallId: string;
+  toolName: string;
+  type: "call";
+} | {
+  output: string;
+  seq: number;
+  status?: "approved" | "rejected";
+  toolCallId?: string;
+  toolName?: string;
+  type: "result";
+} | {
+  seq: number;
+  toolCallId?: string;
+  toolName?: string;
+  type: "awaiting-approval";
+} | {
+  seq: number;
+  toolCallId?: string;
+  toolName?: string;
+  type: "awaiting-secret";
+};
+interface AgentToolEventsHandle {
+  /**
+   * The thread's tool events: the durable lifecycle (oldest first, by `seq`)
+   * followed by any in-flight ephemeral progress events, recomputed from the live
+   * subscription + stream. Read with `$events`. With no `stream` reference only
+   * the durable lifecycle is surfaced. Treat as derived, not identity-stable.
+   */
+  events: Readable<ReadonlyArray<AgentToolEvent>>;
+}
+/**
+ * A focused view of a thread's tool activity: tool calls, their results,
+ * human-in-the-loop approval pauses, and live `ctx.reportProgress(...)` events —
+ * without the full chat message surface. The Svelte counterpart to React's
+ * `useAgentToolEvents`, re-expressed as a readable store you read with `$`.
+ *
+ * It composes the existing primitives rather than adding transport:
+ * {@link subscription} over `api.agents.agentMessages` for the durable lifecycle
+ * and {@link stream} over the optional app event stream for ephemeral progress,
+ * combined through `derived`. Progress events are live-only (the durable path never
+ * emits them): they ride the same sink as token deltas and are surfaced here,
+ * correlated to their tool call by `toolCallId`. For the conversational surface
+ * (messages + streaming text + approvals) use `agentChat`; this handle is the
+ * tool-observability slice.
+ *
+ * The underlying subscription and stream are lazy — they open when `events` gains
+ * its first subscriber and tear down when the last one leaves — so there is no
+ * `teardown` to call (unlike the write-bearing `agentChat`).
+ *
+ * Pass `client` explicitly, or omit it to resolve the ambient client published by
+ * `setLunoraClient`.
+ */
+declare function agentToolEvents(options: AgentToolEventsOptions): AgentToolEventsHandle;
+declare function agentToolEvents(client: LunoraClient, options: AgentToolEventsOptions): AgentToolEventsHandle;
+/**
+ * Publish a {@link LunoraClient} on the Svelte component context so that
+ * descendant components can read it with {@link getLunoraClient} (or implicitly,
+ * via the default-client lookups inside `query`/`mutation`/`hydratePreloaded`).
+ *
+ * Call this once, high in the tree (typically your root `+layout.svelte` or
+ * `App.svelte`), during component initialisation — `setContext` must run while
+ * the component is being constructed, exactly like React's provider mounts once.
+ * This is the Svelte analogue of mounting `LunoraProvider`.
+ */
 declare const setLunoraClient: (client: LunoraClient) => LunoraClient;
 /**
-* Read the {@link LunoraClient} published by {@link setLunoraClient} from the
-* nearest ancestor. Throws if no provider is mounted, mirroring `useLunora`'s
-* "must be used inside a LunoraProvider" guard so the failure is loud and
-* early rather than a confusing `undefined` deref later.
-*
-* Must be called during component initialisation (Svelte's `getContext`
-* constraint); the live stores returned by `query`/`hydratePreloaded` resolve
-* the client eagerly at call time for exactly this reason.
-*/
+ * Read the {@link LunoraClient} published by {@link setLunoraClient} from the
+ * nearest ancestor. Throws if no provider is mounted, mirroring `useLunora`'s
+ * "must be used inside a LunoraProvider" guard so the failure is loud and
+ * early rather than a confusing `undefined` deref later.
+ *
+ * Must be called during component initialisation (Svelte's `getContext`
+ * constraint); the live stores returned by `query`/`hydratePreloaded` resolve
+ * the client eagerly at call time for exactly this reason.
+ */
 declare const getLunoraClient: () => LunoraClient;
 interface AuthStore {
   /** Set the auth token on the underlying `LunoraClient`. */
   setToken: (token: string | null) => void;
+  /**
+   * Readable store of the resolved auth state. Branch on this, not on
+   * `$user === null` — see the contract in `@lunora/client/auth`; `user` is
+   * `null` both when signed out and when a held credential's identity could
+   * not be resolved.
+   */
+  status: Readable<AuthStatus>;
   /** Readable store of the auth token (`null` when signed out). */
   token: Readable<string | null>;
   /** Readable store of the resolved user (`null` when signed out or still loading). */
   user: Readable<User | null>;
 }
 /**
-* Create a pair of Svelte readable stores tracking the auth token and the
-* resolved user identity. The stores are lazy: subscriptions open on the first
-* reader and close when the last unsubscribes. Calling `setToken(jwt)` after
-* sign-in refreshes both stores.
-*
-* Pass an explicit client to bypass the ambient context (useful in tests).
-*/
+ * Create a pair of Svelte readable stores tracking the auth token and the
+ * resolved user identity. The stores are lazy: subscriptions open on the first
+ * reader and close when the last unsubscribes. Calling `setToken(jwt)` after
+ * sign-in refreshes both stores.
+ *
+ * Both subscribes are client-only, like every other subscribing primitive here:
+ * `$token` / `$user` in a template subscribe during `renderToString`. For the
+ * user store that is not just a stray listener — the identity store kicks off
+ * `getCurrentUser()` on its first subscriber, so an unguarded server render
+ * issues a round-trip against a client whose URL does not resolve there. Both
+ * stores still report the client's current values on the server; only the live
+ * updates are withheld, until hydration.
+ *
+ * Pass an explicit client to bypass the ambient context (useful in tests).
+ */
 declare const auth: (explicitClient?: ReturnType<typeof getLunoraClient>) => AuthStore;
+/** Derived auth-gate stores for template gating (`{#if $isAuthenticated}`), built on {@link auth}. */
+interface AuthGateStore {
+  /** Readable store, `true` once a credential is held and nothing has contradicted it. */
+  isAuthenticated: Readable<boolean>;
+  /** Readable store, `true` while a credential's first identity resolve is in flight. */
+  isLoading: Readable<boolean>;
+}
+/**
+ * Derived auth-gate stores built on {@link auth}. Svelte has no JSX-style
+ * `Authenticated` slot component the way React/Vue/Solid do (this package is
+ * plain `.ts` over stores — no `.svelte` component compiler required), so this
+ * exposes the same three-state logic as two boolean stores instead, mapped from
+ * the shared `AuthStatus` contract in `@lunora/client/auth`: a credential whose
+ * first identity resolve is in flight is `isLoading`; a credential nothing has
+ * contradicted — including one whose identity endpoint is unreachable — is
+ * `isAuthenticated`; no session is neither (the signed-out state a template
+ * checks for with a plain `{:else}`).
+ *
+ * ```ts
+ * import { authGate } from "@lunora/svelte";
+ * const { isAuthenticated, isLoading } = authGate();
+ * // markup: {#if $isAuthenticated} signed in {:else if $isLoading} loading… {:else} signed out {/if}
+ * ```
+ *
+ * Pass an explicit client to bypass the ambient context (useful in tests).
+ */
+declare const authGate: (explicitClient?: ReturnType<typeof getLunoraClient>) => AuthGateStore;
 /** The shape held by a {@link connectionStatus} store: the latest aggregate live-socket status. */
 type ConnectionStatusStore = Readable<ConnectionStatus>;
 /**
-* Expose the client's aggregate live-socket status as a Svelte readable store.
-* Read it with the `$store` idiom (`{$status}`) and it stays current: the value
-* transitions through `idle` → `connecting` → `connected` → `offline` as
-* sockets open and drop — the Svelte equivalent of `@lunora/react`'s
-* `useConnectionStatus`. Use it to drive a connection indicator.
-*
-* The status listener attaches inside `readable`'s start callback (on the first
-* `$`-read / `.subscribe()`) and is released by the returned stop function when
-* the last subscriber goes away, so a store that's never read attaches nothing.
-*
-* Pass `client` explicitly, or omit it to resolve the ambient client published
-* by `setLunoraClient` (which must therefore be called during component init,
-* before this runs).
-*/
+ * Expose the client's aggregate live-socket status as a Svelte readable store.
+ * Read it with the `$store` idiom (`{$status}`) and it stays current: the value
+ * transitions through `idle` → `connecting` → `connected` → `offline` as
+ * sockets open and drop — the Svelte equivalent of `@lunora/react`'s
+ * `useConnectionStatus`. Use it to drive a connection indicator.
+ *
+ * The status listener attaches inside `readable`'s start callback (on the first
+ * `$`-read / `.subscribe()`) and is released by the returned stop function when
+ * the last subscriber goes away, so a store that's never read attaches nothing.
+ *
+ * Client-only, like every other subscribing primitive here: `$status` in a
+ * template subscribes during `renderToString`, so an unguarded start callback
+ * registers a listener per server render. The store still reports the client's
+ * current status on the server — that value is a plain read, and nothing
+ * transitions during a render.
+ *
+ * Pass `client` explicitly, or omit it to resolve the ambient client published
+ * by `setLunoraClient` (which must therefore be called during component init,
+ * before this runs).
+ */
 declare const connectionStatus: (client?: LunoraClient) => ConnectionStatusStore;
-/** A targeting context merged on top of the app's default (`defineFlags({ identify })`). */
-type FlagContext = Record<string, unknown>;
 /** The value kinds a flag resolves to — OpenFeature's boolean / number / string / structured (JSON) flags. */
 type FlagValue = boolean | number | string | {
   [key: string]: unknown;
 } | unknown[] | null;
 /**
-* Open a single feature flag as a Svelte readable store, live over Lunora's
-* WebSocket. Read it with the `$store` idiom (`{$darkMode}`).
-*
-* The store holds `defaultValue` until the first evaluation lands, then the
-* server's resolved value — re-emitted whenever the provider re-evaluates (e.g. a
-* flag is toggled in Cloudflare Flagship). The flag's kind is inferred from
-* `defaultValue`'s runtime type, so `flag("dark", false)` reads a boolean and
-* `flag("hero", "control")` a string. `context` supplies a per-call targeting
-* context merged on top of the app's default `identify` targeting key.
-*
-* The subscription opens lazily on the first `$`-read and tears down when the
-* last subscriber detaches. Pass `client` explicitly, or omit it to resolve the
-* ambient client published by `setLunoraClient`. Evaluation never throws — a
-* provider error resolves the default (the same fail-open contract as `ctx.flags`).
-*/
-declare function flag<T extends FlagValue>(key: string, defaultValue: T, context?: FlagContext): Readable<T>;
-declare function flag<T extends FlagValue>(client: LunoraClient, key: string, defaultValue: T, context?: FlagContext): Readable<T>;
-/**
-* Open several feature flags at once as a single Svelte readable store of the
-* resolved record, live over Lunora's WebSocket.
-*
-* Pass a record of `key → defaultValue`; each flag's kind is inferred from its
-* default, and the store holds the same-shaped record with resolved values (the
-* defaults until each evaluation lands). A single `context` applies to every
-* flag. This is the batched form of {@link flag} — one store, one subscription
-* per key, torn down together when the last subscriber detaches.
-*
-* Pass `client` explicitly, or omit it to resolve the ambient client published
-* by `setLunoraClient`.
-*/
-declare function flags<T extends Record<string, FlagValue>>(flagDefaults: T, context?: FlagContext): Readable<T>;
-declare function flags<T extends Record<string, FlagValue>>(client: LunoraClient, flagDefaults: T, context?: FlagContext): Readable<T>;
-/**
-* Hydrate a query store from a {@link Preloaded} token produced by
-* `preloadQuery` during SSR, then keep it live — the reactive-loader handoff.
-*
-* The store is seeded **synchronously** with `preloaded.value`, so the very
-* first read (`$store` during hydration) returns the server value with no
-* loading flash and no hydration mismatch — there is no `undefined` window and
-* no refetch. When the store gains its first subscriber on the client, a live
-* WS subscription attaches and every subsequent delta re-emits, exactly like a
-* plain `query` store. This is the Svelte equivalent of React's
-* `usePreloadedQuery`.
-*
-* Pass `client` explicitly, or omit it to resolve the ambient client published
-* by `setLunoraClient`.
-*
-* Note on SSR: `readable`'s start callback only runs when the store is actually
-* subscribed (the browser), so on the server the store simply holds the seeded
-* value and opens no socket. The token's `value` is the single source of truth
-* for the first paint either way.
-*/
-declare const hydratePreloaded: <T>(preloaded: Preloaded<T>, client?: LunoraClient) => Readable<T>;
-/**
-* The reactive handle returned by {@link mutation} — the Svelte counterpart to
-* React's `useMutation`, re-expressed as stores you read with `$`. The surface
-* is identical across the Lunora adapters (`@lunora/solid`, `/vue`):
-* `data`/`error`/`pending` are readable stores and `mutate` is an awaitable.
-*/
+ * Open a single feature flag as a Svelte readable store, live over Lunora's
+ * WebSocket. Read it with the `$store` idiom (`{$darkMode}`).
+ *
+ * The store holds `defaultValue` until the first evaluation lands, then the
+ * server's resolved value — re-emitted whenever the provider re-evaluates (e.g. a
+ * flag is toggled in Cloudflare Flagship). The flag's kind is inferred from
+ * `defaultValue`'s runtime type, so `flag("dark", false)` reads a boolean and
+ * `flag("hero", "control")` a string.
+ *
+ * The reactive channel is public, so the server evaluates every flag under the
+ * socket's own verified identity — the targeting key your `defineFlags({
+ * identify })` derives — and accepts no client-supplied targeting context. For
+ * evaluation under a context you compute, call `ctx.flags.*` inside a query,
+ * mutation, or action and return the resolved value.
+ *
+ * The subscription opens lazily on the first `$`-read and tears down when the
+ * last subscriber detaches. Pass `client` explicitly, or omit it to resolve the
+ * ambient client published by `setLunoraClient`. Evaluation never throws — a
+ * provider error resolves the default (the same fail-open contract as `ctx.flags`).
+ */
+declare function flag<T extends FlagValue>(key: string, defaultValue: T): Readable<T>;
+declare function flag<T extends FlagValue>(client: LunoraClient, key: string, defaultValue: T): Readable<T>;
+/**
+ * Open several feature flags at once as a single Svelte readable store of the
+ * resolved record, live over Lunora's WebSocket.
+ *
+ * Pass a record of `key → defaultValue`; each flag's kind is inferred from its
+ * default, and the store holds the same-shaped record with resolved values (the
+ * defaults until each evaluation lands). This is the batched form of {@link flag}
+ * — one store, one subscription per key, torn down together when the last
+ * subscriber detaches. Like {@link flag} it evaluates under the socket's
+ * server-verified identity only.
+ *
+ * Pass `client` explicitly, or omit it to resolve the ambient client published
+ * by `setLunoraClient`.
+ */
+declare function flags<T extends Record<string, FlagValue>>(flagDefaults: T): Readable<T>;
+declare function flags<T extends Record<string, FlagValue>>(client: LunoraClient, flagDefaults: T): Readable<T>;
+/**
+ * Hydrate a query store from a {@link Preloaded} token produced by
+ * `preloadQuery` during SSR, then keep it live — the reactive-loader handoff.
+ *
+ * The store is seeded **synchronously** with `preloaded.value`, so the very
+ * first read (`$store` during hydration) returns the server value with no
+ * loading flash and no hydration mismatch — no `undefined` window (until an
+ * identity is retired, see below) and no refetch. When the store gains its
+ * first subscriber on the client, a live WS subscription attaches and every
+ * subsequent delta re-emits, exactly like a plain `query` store. This is the
+ * Svelte equivalent of React's `usePreloadedQuery`.
+ *
+ * Pass `client` explicitly, or omit it to resolve the ambient client published
+ * by `setLunoraClient`. Pass `onError` to surface a subscription-scoped error the
+ * server pushes (a session expiry, an RLS denial); without it such an error is
+ * dropped and the store keeps rendering the SSR snapshot as if it were live.
+ *
+ * Note on SSR: `readable`'s start callback DOES run on the server — svelte's
+ * server runtime resolves `{$store}` by subscribing to it — so the socket is
+ * opened behind an explicit `isBrowser()` guard rather than left to the store's
+ * laziness. On the server the store simply holds the seeded value. The token's
+ * `value` is the single source of truth for the first paint either way.
+ *
+ * The preloaded value was read for whoever was signed in when the page loaded.
+ * After a sign-out or user switch retires that identity
+ * (`client.identityEpoch() > 0`), every `hydratePreloaded` store on the client
+ * (subscribed then or later) stops using it and holds `undefined` until the live
+ * value arrives — matching `@lunora/react`'s `usePreloadedQuery`, hence the
+ * `Readable<T | undefined>` type.
+ */
+declare const hydratePreloaded: <T>(preloaded: Preloaded<T>, client?: LunoraClient, options?: {
+  onError?: SubscriptionErrorCallback;
+}) => Readable<T | undefined>;
+/**
+ * `liveTopic` — follow one live topic on the connection shared by its stream's route.
+ *
+ * A thin lifecycle wrapper over `subscribeLiveTopic` from `@lunora/client`. The
+ * subscription opens when the store gets its first subscriber and closes when it
+ * loses its last one, so there is no `teardown()` to call. Like the other stores
+ * here, a server render subscribes and opens nothing.
+ *
+ * The `LunoraClient` is read from context when `liveTopic` is CALLED, so call it while a
+ * component initialises: `getContext` throws outside that window.
+ */
+/** The state a `liveTopic` store holds. */
+interface LiveTopicState<Payload = unknown> {
+  /** The shard's refusal of this subscription (403, 409, 429 and similar), or `undefined`. */
+  error: LiveStreamSubscribeError | undefined;
+  /** The last payload delivered on the topic, or `undefined` until the first event. */
+  lastEvent: Payload | undefined;
+}
+/**
+ * Follow the topic `topic` names on the shared live connection for its stream's route. Pass the
+ * reference `_generated/live.ts` hands out (`live.posts.post({ postId })`), or a `Readable` of one.
+ * `options` may be a `Readable` too, e.g. to move to a new `sessionKey` on sign-out. A new emission
+ * resubscribes only when the topic or the connection options (including `sessionKey`) change;
+ * `onEvent` and `onError` are read at call time, so a new identity never reopens the subscription.
+ * The route is resolved against the `LunoraClient` from context, and `lastEvent` and `onEvent` are
+ * typed by the payload the topic declares.
+ */
+declare const liveTopic: <Payload>(topic: LiveTopicRef<Payload> | Readable<LiveTopicRef<Payload>>, options?: LiveTopicOptions<Payload> | Readable<LiveTopicOptions<Payload>>) => Readable<LiveTopicState<Payload>>;
+/**
+ * The reactive handle returned by {@link mutation} — the Svelte counterpart to
+ * React's `useMutation`, re-expressed as stores you read with `$`. The surface
+ * is identical across the Lunora adapters (`@lunora/solid`, `/vue`):
+ * `data`/`error`/`pending` are readable stores and `mutate` is an awaitable.
+ */
 interface MutationHandle<F extends FunctionReference> {
   /** The latest invocation's resolved value, or `undefined` before the first success. */
   data: Readable<ReturnOf<F> | undefined>;
   /** The latest invocation's error, or `undefined`. */
   error: Readable<Error | undefined>;
   /**
-  * Run the mutation. Resolves with the server result and rejects on failure
-  * (errors propagate — there is no swallowing). Optimistic updates passed in
-  * `options` are applied and rolled back by the client against the live query
-  * subscriptions, exactly as in the React adapter.
-  */
-  mutate: (args: ArgsOf<F>, options?: MutationCallOptions<unknown, unknown, ArgsOf<F>>) => Promise<ReturnOf<F>>;
-  /**
-  * `true` while any invocation from this handle is in flight. Ref-counted, so
-  * overlapping calls compose and it only flips back to `false` once the last
-  * one settles. Read it with `$pending` in a component to disable a button.
-  */
+   * Run the mutation. Resolves with the server result and rejects on failure
+   * (errors propagate — there is no swallowing). Optimistic updates passed in
+   * `options` are applied and rolled back by the client against the live query
+   * subscriptions, exactly as in the React adapter.
+   */
+  mutate: (args: ArgsOf<F>, options?: MutationCallOptions<unknown, unknown, ArgsOf<F>> & OnlineOnlyOption<F>) => Promise<ReturnOf<F>>;
+  /**
+   * `true` while any invocation from this handle is in flight. Ref-counted, so
+   * overlapping calls compose and it only flips back to `false` once the last
+   * one settles. Read it with `$pending` in a component to disable a button.
+   */
   pending: Readable<boolean>;
   /** Clear `data`/`error` back to idle. */
   reset: () => void;
 }
 /**
-* Create an optimistic {@link MutationHandle} for a mutation reference. The
-* Svelte counterpart to React's `useMutation`: returns
-* `{ data, error, pending, mutate, reset }` of readable stores plus an awaitable
-* `mutate`. The ref-counted pending + error-normalize orchestration is the
-* shared `createMutationRunner` from `@lunora/client`; only the stores are
-* adapter-specific.
-*
-* Pass `client` explicitly, or omit it to resolve the ambient client published
-* by `setLunoraClient`.
-*/
+ * Create an optimistic {@link MutationHandle} for a mutation reference. The
+ * Svelte counterpart to React's `useMutation`: returns
+ * `{ data, error, pending, mutate, reset }` of readable stores plus an awaitable
+ * `mutate`. The ref-counted pending + error-normalize orchestration is the
+ * shared `createCallRunner` from `@lunora/client`; only the stores are
+ * adapter-specific.
+ *
+ * `data`/`error` follow the adapter-wide contract: both track the LATEST
+ * invocation (an earlier call settling later cannot clobber a newer one), a
+ * success clears `error`, and a failure leaves the previous `data` in place.
+ * `reset()` clears both; it does not cancel an in-flight call.
+ *
+ * Pass `client` explicitly, or omit it to resolve the ambient client published
+ * by `setLunoraClient`.
+ */
 declare function mutation<F extends FunctionReference>(function_: F): MutationHandle<F>;
 declare function mutation<F extends FunctionReference>(client: LunoraClient, function_: F): MutationHandle<F>;
 /**
-* The reactive handle returned by {@link mutator} — the Svelte counterpart to
-* `@lunora/react`'s `useMutator`, re-expressed as stores you read with `$`.
-* `error`/`isError`/`pending` are readable stores and `mutate` is an awaitable
-* that resolves once the write is persisted (or rejects).
-*/
+ * The reactive handle returned by {@link mutator} — the Svelte counterpart to
+ * `@lunora/react`'s `useMutator`, re-expressed as stores you read with `$`.
+ * `error`/`isError`/`pending` are readable stores and `mutate` is an awaitable
+ * that resolves once the write is persisted (or rejects).
+ */
 interface MutatorHandleStore<TArgs> {
   /** The latest invocation's error, or `undefined`. */
   error: Readable<Error | undefined>;
@@ -179,20 +830,22 @@ interface MutatorHandleStore<TArgs> {
   reset: () => void;
 }
 /**
-* Ergonomic `{ mutate, pending, error, isError, reset }` wrapper over a bound
-* custom-mutator handle from `@lunora/db`'s `bindMutators` — the Svelte
-* equivalent of `@lunora/react`'s `useMutator`. The optimistic overlay and
-* server-authoritative push are owned by the bound handle (and TanStack DB's
-* optimistic-transaction layer rebases pending overlays on every sync tick);
-* this helper only surfaces store state for the in-flight/error lifecycle. Reads
-* stay on the existing TanStack `useLiveQuery`; no new query store is needed.
-*
-* `pending` is ref-counted across overlapping invocations of THIS handle, so it
-* clears only once every concurrent call has settled.
-*/
+ * Ergonomic `{ mutate, pending, error, isError, reset }` wrapper over a bound
+ * custom-mutator handle from `@lunora/db`'s `bindMutators` — the Svelte
+ * equivalent of `@lunora/react`'s `useMutator`. The optimistic overlay and
+ * server-authoritative push are owned by the bound handle (and TanStack DB's
+ * optimistic-transaction layer rebases pending overlays on every sync tick);
+ * this helper only surfaces store state for the in-flight/error lifecycle. Reads
+ * stay on the existing TanStack `useLiveQuery`; no new query store is needed.
+ *
+ * `pending` is ref-counted across overlapping invocations of THIS handle, so it
+ * clears only once every concurrent call has settled.
+ */
 declare const mutator: <TArgs = Record<string, unknown>>(handle: MutatorHandle<TArgs>) => MutatorHandleStore<TArgs>;
 /** The args a paginated query exposes minus the framework-supplied page cursor. */
 type PaginatedArgs<F extends FunctionReference> = Omit<ArgsOf<F>, "paginationOpts">;
+/** Paginated args, the skip sentinel, or a reactive (`Readable`) source of either. */
+type ReactivePaginatedArgs<F extends FunctionReference> = "skip" | PaginatedArgs<F> | Readable<"skip" | PaginatedArgs<F>>;
 /** The element type of the `page` array a paginated query returns. */
 type PageItemOf<F extends FunctionReference> = ReturnOf<F> extends {
   page: (infer T)[];
@@ -200,9 +853,18 @@ type PageItemOf<F extends FunctionReference> = ReturnOf<F> extends {
 interface PaginatedQueryOptions {
   /** Page size for the first page (and the default for `loadMore`). */
   initialNumItems: number;
+  /** Called when a page subscription reports an error (also surfaced on the `error` store). */
+  onError?: SubscriptionErrorCallback;
   shardKey?: string;
 }
 interface PaginatedQueryHandle<T> {
+  /**
+   * The last page subscription error, or `undefined`. A tail page that fails
+   * before its first frame is dropped so `status` returns to `"CanLoadMore"`
+   * and `loadMore` can retry it; cleared by the next successful frame,
+   * `loadMore`, or an args emission.
+   */
+  error: Readable<SubscriptionError | undefined>;
   /** `true` while the first page or a `loadMore` page is in flight. */
   isLoading: Readable<boolean>;
   /** Request the next page. A no-op unless `status === "CanLoadMore"`. */
@@ -214,9 +876,13 @@ interface PaginatedQueryHandle<T> {
 interface InfiniteQueryOptions {
   /** Page size for the first page (and the default for `fetchNextPage`). */
   initialNumItems: number;
+  /** Called when a page subscription reports an error (also surfaced on the `error` store). */
+  onError?: SubscriptionErrorCallback;
   shardKey?: string;
 }
 interface InfiniteQueryHandle<T> {
+  /** The last page subscription error, or `undefined` — see `PaginatedQueryHandle.error`. */
+  error: Readable<SubscriptionError | undefined>;
   /** Request the next page. A no-op unless `status === "CanLoadMore"`. */
   fetchNextPage: (numberItems?: number) => void;
   /** `true` when the loaded tail reports it can load another page. */
@@ -230,46 +896,50 @@ interface InfiniteQueryHandle<T> {
   status: Readable<PaginationStatus>;
 }
 /**
-* Open a live paginated query as Svelte stores. The first page opens when
-* called; call `loadMore(n)` to append the next page. Results are flattened
-* across all loaded pages.
-*
-* Pass `client` explicitly, or omit it to resolve the ambient client from the
-* Svelte context.
-*/
-declare function paginatedQuery<F extends FunctionReference>(function_: F, args: "skip" | PaginatedArgs<F>, options: PaginatedQueryOptions): PaginatedQueryHandle<PageItemOf<F>>;
-declare function paginatedQuery<F extends FunctionReference>(client: LunoraClient, function_: F, args: "skip" | PaginatedArgs<F>, options: PaginatedQueryOptions): PaginatedQueryHandle<PageItemOf<F>>;
-/**
-* Open a live paginated query as Svelte stores, keeping each page as its own
-* inner array (TanStack-Query-style `fetchNextPage` / `hasNextPage` shape).
-*
-* Pass `client` explicitly, or omit it to resolve the ambient client from the
-* Svelte context.
-*/
+ * Open a live paginated query as Svelte stores. The first page opens when
+ * called; call `loadMore(n)` to append the next page. Results are flattened
+ * across all loaded pages.
+ *
+ * Pass `client` explicitly, or omit it to resolve the ambient client from the
+ * Svelte context.
+ *
+ * `args` may also be a `Readable` store: each emission tears the engine down
+ * and rebuilds it against the new args (pagination resets to the first page);
+ * a `"skip"` emission tears down without re-opening.
+ */
+declare function paginatedQuery<F extends FunctionReference>(function_: F, args: ReactivePaginatedArgs<F>, options: PaginatedQueryOptions): PaginatedQueryHandle<PageItemOf<F>>;
+declare function paginatedQuery<F extends FunctionReference>(client: LunoraClient, function_: F, args: ReactivePaginatedArgs<F>, options: PaginatedQueryOptions): PaginatedQueryHandle<PageItemOf<F>>;
+/**
+ * Open a live paginated query as Svelte stores, keeping each page as its own
+ * inner array (TanStack-Query-style `fetchNextPage` / `hasNextPage` shape).
+ *
+ * Pass `client` explicitly, or omit it to resolve the ambient client from the
+ * Svelte context.
+ */
 declare function infiniteQuery<F extends FunctionReference>(function_: F, args: "skip" | PaginatedArgs<F>, options: InfiniteQueryOptions): InfiniteQueryHandle<PageItemOf<F>>;
 declare function infiniteQuery<F extends FunctionReference>(client: LunoraClient, function_: F, args: "skip" | PaginatedArgs<F>, options: InfiniteQueryOptions): InfiniteQueryHandle<PageItemOf<F>>;
 /**
-* `presence` — collaborative-awareness stores, the client half of the
-* `@lunora/server` `definePresence` preset.
-*
-* Drives the heartbeat mutation (on call, interval, and tab re-focus) and
-* subscribes to the live `listPresent` query for the given room.
-*
-* Pass `client` explicitly, or omit it to resolve the ambient client from the
-* Svelte context.
-*/
-/**
-* A heartbeat mutation reference: takes `{ roomId, sessionId, data? }`.
-*/
+ * `presence` — collaborative-awareness stores, the client half of the
+ * `@lunora/server` `definePresence` preset.
+ *
+ * Drives the heartbeat mutation (on call, interval, and tab re-focus) and
+ * subscribes to the live `listPresent` query for the given room.
+ *
+ * Pass `client` explicitly, or omit it to resolve the ambient client from the
+ * Svelte context.
+ */
+/**
+ * A heartbeat mutation reference: takes `{ roomId, sessionId, data? }`.
+ */
 type HeartbeatReference = FunctionReference<"mutation", {
   data?: Record<string, unknown>;
   roomId: string;
   sessionId: string;
 }>;
 /**
-* A listPresent query reference: takes `{ roomId }` and returns the array of
-* present members.
-*/
+ * A listPresent query reference: takes `{ roomId }` and returns the array of
+ * present members.
+ */
 type ListPresentReference = FunctionReference<"query", {
   roomId: string;
 }>;
@@ -283,14 +953,22 @@ interface PresenceOptions<H extends HeartbeatReference, L extends ListPresentRef
   /** The `api.*` reference for the presence listPresent query. */
   listPresent: L;
   /**
-  * Stable id for this presence row. Defaults to a fresh per-mount id.
-  * Pass a user/connection id to control deduping across tabs.
-  */
+   * Called when the `listPresent` subscription reports an error (a session
+   * expiry, an RLS denial). Without it — and without reading `error` — such a
+   * failure is invisible and `present` freezes at its last value.
+   */
+  onError?: SubscriptionErrorCallback;
+  /**
+   * Stable id for this presence row. Defaults to a fresh per-mount id.
+   * Pass a user/connection id to control deduping across tabs.
+   */
   sessionId?: string;
   /** Forwarded to the heartbeat mutation / listPresent subscription when sharding by room. */
   shardKey?: string;
 }
 interface PresenceHandle<L extends ListPresentReference> {
+  /** The `listPresent` subscription's last error, or `undefined`. */
+  error: Readable<SubscriptionError | undefined>;
   /** The present members for the room. `undefined` until the first push. */
   present: Readable<ReturnOf<L> | undefined>;
   /** This handle's session id. */
@@ -301,17 +979,22 @@ interface PresenceHandle<L extends ListPresentReference> {
   teardown: () => void;
 }
 /**
-* Open a live presence handle.
-*
-* Pass `client` explicitly, or omit it to resolve the ambient client from the
-* Svelte context (requires calling inside a component's `&lt;script>` block or
-* inside a function called during component initialisation).
-*
-* Call `teardown()` when the component is destroyed to stop heartbeats and
-* remove the visibility listener (`onDestroy(handle.teardown)`).
-*/
+ * Open a live presence handle.
+ *
+ * Pass `client` explicitly, or omit it to resolve the ambient client from the
+ * Svelte context (requires calling inside a component's `<script>` block or
+ * inside a function called during component initialisation).
+ *
+ * Teardown (stop heartbeats, remove the visibility listener, release the
+ * connection context) is wired automatically to the component's `onDestroy`
+ * when called during component initialisation. Outside a component call
+ * `handle.teardown()` yourself. `teardown()` is idempotent, so an explicit
+ * `onDestroy(handle.teardown)` on top of the auto-wiring is safe.
+ */
 declare function presence<H extends HeartbeatReference, L extends ListPresentReference>(roomId: string, options: PresenceOptions<H, L>): PresenceHandle<L>;
 declare function presence<H extends HeartbeatReference, L extends ListPresentReference>(client: LunoraClient, roomId: string, options: PresenceOptions<H, L>): PresenceHandle<L>;
+/** Query args, the skip sentinel, or a reactive (`Readable`) source of either. */
+type ReactiveArgs<F extends FunctionReference> = ArgsOf<F> | "skip" | Readable<ArgsOf<F> | "skip">;
 /** Options accepted by {@link query}. */
 interface QueryStoreOptions {
   /** Called when the underlying subscription reports an error. */
@@ -320,36 +1003,48 @@ interface QueryStoreOptions {
   shardKey?: string;
 }
 /**
-* The shape held by a {@link query} store: the latest server value (`undefined`
-* until the first response lands, mirroring React's `useQuery`).
-*/
+ * The shape held by a {@link query} store: the latest server value (`undefined`
+ * until the first response lands, mirroring React's `useQuery`).
+ */
 type QueryStore<F extends FunctionReference> = Readable<ReturnOf<F> | undefined>;
 /**
-* Open a live query as a Svelte readable store. Read it with the `$store`
-* idiom in a component (`{$messages}`) and it stays current: a WS subscription
-* attaches the moment the store gains its first subscriber and the value
-* re-emits on every server delta — the Svelte equivalent of React's `useQuery`.
-*
-* The subscription is opened lazily (inside `readable`'s start callback, on the
-* first `$`-read / `.subscribe()`) and torn down by the returned stop function
-* when the last subscriber goes away — so a store that's never read opens no
-* socket, and a component that unmounts releases its subscription. Sharing one
-* store across several components shares a single underlying subscription
-* (the `LunoraClient` de-dupes by `(fn, args, shardKey)`).
-*
-* Pass `client` explicitly, or omit it to resolve the ambient client published
-* by `setLunoraClient` (which must therefore be called during component init,
-* before this runs).
-*/
-declare function query<F extends FunctionReference>(function_: F, args: ArgsOf<F>, options?: QueryStoreOptions): QueryStore<F>;
-declare function query<F extends FunctionReference>(client: LunoraClient, function_: F, args: ArgsOf<F>, options?: QueryStoreOptions): QueryStore<F>;
+ * Open a live query as a Svelte readable store. Read it with the `$store`
+ * idiom in a component (`{$messages}`) and it stays current: a WS subscription
+ * attaches the moment the store gains its first subscriber and the value
+ * re-emits on every server delta — the Svelte equivalent of React's `useQuery`.
+ *
+ * The subscription is opened lazily (inside `readable`'s start callback, on the
+ * first `$`-read / `.subscribe()`) and only in the browser — a server render
+ * reads the store's `undefined` seed and opens nothing. It is torn down by the
+ * returned stop function when the last subscriber goes away — so a store that's
+ * never read opens no socket, and a component that unmounts releases its
+ * subscription. Sharing one
+ * store across several components shares a single underlying subscription
+ * (the `LunoraClient` de-dupes by `(fn, args, shardKey)`).
+ *
+ * Pass `"skip"` as `args` to keep the store connected but the subscription
+ * dormant (the value stays `undefined`, no socket opens) — useful for a query
+ * gated on auth or a route param, matching React/Vue/Solid's `useQuery`.
+ *
+ * Pass `client` explicitly, or omit it to resolve the ambient client published
+ * by `setLunoraClient` (which must therefore be called during component init,
+ * before this runs).
+ *
+ * `args` may also be a `Readable` store (wrap runes state with `toStore` or
+ * `derived`): each emission tears down the previous subscription, resets the
+ * value to `undefined`, and opens a fresh one against the new args — the Svelte
+ * counterpart of Vue's `MaybeRefOrGetter` args. An emission of `"skip"` tears down without
+ * re-opening and resets the value to `undefined`.
+ */
+declare function query<F extends FunctionReference>(function_: F, args: ReactiveArgs<F>, options?: QueryStoreOptions): QueryStore<F>;
+declare function query<F extends FunctionReference>(client: LunoraClient, function_: F, args: ReactiveArgs<F>, options?: QueryStoreOptions): QueryStore<F>;
 interface RateLimitOptions {
   /** Clock injection for tests. Defaults to `Date.now`. */
   now?: () => number;
   /**
-  * Re-evaluation cadence in milliseconds while throttled, so `retryAfter`
-  * ticks down and `disabled` flips back automatically. Defaults to `1000`.
-  */
+   * Re-evaluation cadence in milliseconds while throttled, so `retryAfter`
+   * ticks down and `disabled` flips back automatically. Defaults to `1000`.
+   */
   tickMs?: number;
 }
 interface RateLimitHandle {
@@ -369,19 +1064,67 @@ interface RateLimitHandle {
   teardown: () => void;
 }
 /**
-* Client-side mirror of a rate limit for instant UX — disable a button or show
-* a countdown without a round-trip. It runs the same token-bucket / fixed-window
-* math as `@lunora/ratelimit` on the server, so the prediction agrees with the
-* authoritative check; the server remains the source of truth.
-*
-* `config` is read on every call; pass a stable reference (module constant).
-*
-* Call `teardown()` when the component is destroyed to stop the auto-tick
-* interval (`onDestroy(handle.teardown)`).
-*/
+ * Client-side mirror of a rate limit for instant UX — disable a button or show
+ * a countdown without a round-trip. It runs the same token-bucket / fixed-window
+ * math as `@lunora/ratelimit` on the server, so the prediction agrees with the
+ * authoritative check; the server remains the source of truth.
+ *
+ * `config` is read on every call; pass a stable reference (module constant).
+ *
+ * Call `teardown()` when the component is destroyed to stop the auto-tick
+ * interval (`onDestroy(handle.teardown)`).
+ */
 declare const rateLimit: (config: RateLimitConfig, options?: RateLimitOptions) => RateLimitHandle;
+/** The lifecycle of a stream the store is observing. */
+type StreamStatus = "complete" | "error" | "idle" | "streaming";
+interface StreamStoreOptions {
+  /**
+   * Opt into resume-on-reconnect for a stream the server declared `durable`.
+   * The chunks already received are kept and the socket re-attaches to the same
+   * run, so a dropped connection mid-generation continues instead of surfacing
+   * `STREAM_DISCONNECTED`. Has no effect on an ephemeral stream.
+   */
+  durable?: boolean;
+  /** Forwarded to `client.stream()` — caps the in-flight chunk buffer. */
+  maxBuffer?: number;
+  shardKey?: string;
+}
+interface StreamHandle<T> {
+  /** Force-cancel the stream and resolve the iterator. Safe to call multiple times. */
+  cancel: () => void;
+  /** Svelte readable store of the chunks the server has pushed so far, in arrival order. */
+  chunks: Readable<ReadonlyArray<T>>;
+  /** Svelte readable store of the last stream error (`undefined` when healthy). */
+  error: Readable<Error | undefined>;
+  /** Svelte readable store of the stream lifecycle status. */
+  status: Readable<StreamStatus>;
+  /**
+   * Stop the stream and release the iterator. Call in `onDestroy`
+   * (`onDestroy(handle.teardown)`) when you consume `chunks` eagerly; when you
+   * read `chunks` with `$` the store tears itself down as the last subscriber
+   * leaves.
+   */
+  teardown: () => void;
+}
+/**
+ * Open a streaming query and expose its chunks, lifecycle status, and last error
+ * as Svelte readable stores. The `chunks` store is lazy: the stream opens on the
+ * first browser-side subscriber to `chunks` and is cancelled when the last one
+ * leaves (its chunks reset on the next open); a server render opens nothing.
+ * `status` and `error` mirror that same stream.
+ *
+ * Passing `"skip"` as `args` keeps the stores connected but the stream dormant
+ * (`chunks` stays empty, `status` stays `"idle"`). The Svelte counterpart to
+ * React's `useStream`, re-expressed as stores you read with `$`.
+ *
+ * Pass an explicit `client` as the first argument to bypass the ambient context
+ * (useful in tests), or omit it to resolve the client published by
+ * `setLunoraClient`.
+ */
+declare function stream<F extends FunctionReference<"stream">>(function_: F, args: ArgsOf<F> | "skip", options?: StreamStoreOptions): StreamHandle<ReturnOf<F>>;
+declare function stream<F extends FunctionReference<"stream">>(client: LunoraClient, function_: F, args: ArgsOf<F> | "skip", options?: StreamStoreOptions): StreamHandle<ReturnOf<F>>;
 interface SubscriptionStoreOptions {
-  onError?: (error: Error) => void;
+  onError?: SubscriptionErrorCallback;
   shardKey?: string;
 }
 interface SubscriptionHandle<T> {
@@ -391,15 +1134,239 @@ interface SubscriptionHandle<T> {
   error: Readable<Error | undefined>;
 }
 /**
-* Create a pair of Svelte readable stores that open a live subscription
-* against the Lunora backend. `data` updates on every server push; `error`
-* captures the last subscription error. Both stores are lazy: the subscription
-* opens on the first subscriber to `data` and tears down when it stops.
-*
-* Passing `"skip"` as `args` keeps the stores connected but the subscription
-* dormant (`data` stays `undefined`). Pass an explicit `client` as the first
-* argument to bypass the ambient context (useful in tests).
-*/
-declare function subscription<F extends FunctionReference>(function_: F, args: ArgsOf<F> | "skip", options?: SubscriptionStoreOptions): SubscriptionHandle<ReturnOf<F>>;
-declare function subscription<F extends FunctionReference>(client: LunoraClient, function_: F, args: ArgsOf<F> | "skip", options?: SubscriptionStoreOptions): SubscriptionHandle<ReturnOf<F>>;
-export { type AuthStore, type ConnectionStatusStore, type FlagContext, type FlagValue, type HeartbeatReference, type InfiniteQueryHandle, type InfiniteQueryOptions, type ListPresentReference, type MutationHandle, type MutatorHandleStore, type PageItemOf, type PaginatedArgs, type PaginatedQueryHandle, type PaginatedQueryOptions, type PresenceHandle, type PresenceOptions, type QueryStore, type QueryStoreOptions, type RateLimitHandle, type RateLimitOptions, type SubscriptionHandle, type SubscriptionStoreOptions, auth, connectionStatus, flag, flags, getLunoraClient, hydratePreloaded, infiniteQuery, mutation, mutator, paginatedQuery, presence, query, rateLimit, setLunoraClient, subscription };
+ * Create a pair of Svelte readable stores that open a live subscription
+ * against the Lunora backend. `data` updates on every server push; `error`
+ * captures the last subscription error. Both stores are lazy: the
+ * subscription opens on the first browser-side subscriber to `data` and tears
+ * down when it stops. A server render subscribes too (svelte resolves `{$store}`
+ * that way) and opens nothing.
+ *
+ * Passing `"skip"` as `args` keeps the stores connected but the subscription
+ * dormant (`data` stays `undefined`). Pass an explicit `client` as the first
+ * argument to bypass the ambient context (useful in tests).
+ *
+ * `args` may also be a `Readable` store: each emission tears down the previous
+ * subscription, resets `data` to `undefined`, and opens a fresh one; a `"skip"`
+ * emission tears down without re-opening.
+ */
+declare function subscription<F extends FunctionReference>(function_: F, args: ReactiveArgs<F>, options?: SubscriptionStoreOptions): SubscriptionHandle<ReturnOf<F>>;
+declare function subscription<F extends FunctionReference>(client: LunoraClient, function_: F, args: ReactiveArgs<F>, options?: SubscriptionStoreOptions): SubscriptionHandle<ReturnOf<F>>;
+/**
+ * Browser Web Audio subsystems for `useVoiceAgent` — the default microphone
+ * capture and speaker playback implementations injected into the composable via
+ * its `createMicrophone` / `createSpeaker` seams. Kept in a sibling module so the
+ * heavy Web Audio graph (and its structural DOM typings) stays isolated from the
+ * composable's transport + reactive-state logic and remains mockable in a
+ * non-browser test env.
+ */
+/**
+ * The negotiated audio format the voice DO streams back. Mirrors
+ * `@lunora/agent`'s `VoiceServerFrame` `ready.audioFormat` — re-declared (not
+ * imported) so this Svelte package never pulls in the server-only `@lunora/agent`
+ * module graph.
+ */
+type VoiceAudioFormat = "mp3" | "wav";
+/** Captures microphone audio and reports level / turn boundaries back to the composable. */
+interface VoiceMicrophone {
+  /** Mute/unmute the mic without tearing down the capture graph. */
+  setMuted: (muted: boolean) => void;
+  /** Stop capture and release the media stream + audio graph. */
+  stop: () => void;
+}
+/** Plays the server's streamed audio chunks and supports a mid-utterance barge-in. */
+interface VoiceSpeaker {
+  /** Queue a decoded audio chunk for gap-minimized playback. */
+  enqueue: (audio: Uint8Array) => void;
+  /** Drop everything queued and stop the current chunk (barge-in). */
+  interrupt: () => void;
+  /** Release the playback audio context. */
+  stop: () => void;
+}
+/** Config passed to a {@link CreateMicrophone} factory. */
+interface MicrophoneConfig {
+  /** The consecutive above-threshold chunk count that counts as a barge-in. */
+  interruptChunks: number;
+  /** RMS above which the user is considered to be barging in while the agent speaks. */
+  interruptThreshold: number;
+  /**
+   * `true` from the moment a turn is committed until it completes — the whole
+   * `thinking` + `speaking` window, not just the audible half.
+   *
+   * It gates BOTH branches below, and the wider span is the point. Gated only
+   * on "audibly speaking", turn detection kept running through the entire
+   * STT+LLM window after a `commit`: room noise at the (deliberately low)
+   * `silenceThreshold` re-armed `sawSpeech`, another quiet gap fired a SECOND
+   * `commit`, and the DO refused it with "a turn is already in progress" —
+   * a refusal that returns before draining the audio buffer, so the PCM
+   * captured since the first commit leaked into the next utterance.
+   *
+   * A genuine barge-in still works in that window: it routes through the
+   * `onInterrupt` branch, which needs `interruptChunks` consecutive chunks at
+   * `interruptThreshold` — an order of magnitude above `silenceThreshold` —
+   * and `interrupt` is exactly what the DO tells the client to send.
+   */
+  isTurnActive: () => boolean;
+  /** One 16 kHz mono 16-bit little-endian PCM frame captured from the mic. */
+  onAudio: (pcm: Uint8Array) => void;
+  /** A barge-in was detected (RMS spike while the agent is speaking). */
+  onInterrupt: () => void;
+  /** The current input RMS (0–1), for a level meter. */
+  onLevel: (rms: number) => void;
+  /** A spoken utterance ended (speech followed by `silenceDurationMs` of silence). */
+  onSilence: () => void;
+  /** Milliseconds of sub-threshold audio (after speech) that closes an utterance. */
+  silenceDurationMs: number;
+  /** RMS below which audio counts as silence. */
+  silenceThreshold: number;
+}
+type CreateMicrophone = (config: MicrophoneConfig) => Promise<VoiceMicrophone>;
+type CreateSpeaker = (config: {
+  audioFormat: VoiceAudioFormat;
+}) => VoiceSpeaker;
+/**
+ * The `agents.<name>Voice` reference codegen emits for a voice-enabled agent — a
+ * live, WS-backed session keyed by `threadKey`. A structural subset of the
+ * generated member, so passing `api.agents.<name>Voice` type-checks.
+ */
+type VoiceReference = FunctionReference<"stream", {
+  threadKey: string;
+}, Record<string, unknown>>;
+/** The lifecycle of a voice call, mirrored to the UI. */
+type VoiceStatus = "idle" | "listening" | "speaking" | "thinking";
+/** A minimal structural subset of the DOM `WebSocket` the handle drives. */
+interface VoiceSocket {
+  binaryType: string;
+  close: () => void;
+  onclose: ((event: unknown) => void) | null;
+  onerror: ((event: unknown) => void) | null;
+  onmessage: ((event: {
+    data: unknown;
+  }) => void) | null;
+  onopen: ((event: unknown) => void) | null;
+  readonly readyState: number;
+  send: (data: ArrayBufferView | ArrayBufferLike | string) => void;
+}
+type CreateSocket = (url: string) => VoiceSocket;
+interface VoiceAgentOptions {
+  /**
+   * Advanced/test seam: build the microphone capture subsystem. Defaults to a
+   * `getUserMedia` + Web Audio implementation. Injected wholesale so the Web
+   * Audio graph stays isolated (and mockable in a non-browser test env).
+   */
+  createMicrophone?: CreateMicrophone;
+  /**
+   * Advanced/test seam: open the transport. Defaults to the WebSocket
+   * implementation the client was built with (`client.getWebSocketImpl()`),
+   * NOT a raw `globalThis.WebSocket`.
+   */
+  createSocket?: CreateSocket;
+  /** Advanced/test seam: build the audio playback subsystem. Defaults to a Web Audio implementation. */
+  createSpeaker?: CreateSpeaker;
+  /** Consecutive above-`interruptThreshold` chunks that trigger a barge-in. Default `3`. */
+  interruptChunks?: number;
+  /** Input RMS above which the user is treated as barging in while the agent speaks. Default `0.15`. */
+  interruptThreshold?: number;
+  /** Milliseconds of silence (after speech) that auto-commits an utterance. Default `1200`. */
+  silenceDurationMs?: number;
+  /** Input RMS below which audio counts as silence. Default `0.01`. */
+  silenceThreshold?: number;
+  /** The thread to converse on — shared with the agent's text turns. */
+  threadKey: string;
+  /** The generated `api.agents.<name>Voice` reference — identifies the voice DO endpoint. */
+  voice: VoiceReference;
+}
+interface VoiceAgentHandle {
+  /** Svelte readable store of the current input RMS (0–1) — drive a mic level meter. Read with `$audioLevel`. */
+  audioLevel: Readable<number>;
+  /** Svelte readable store: `true` once the WS `ready` handshake completed. Read with `$connected`. */
+  connected: Readable<boolean>;
+  /** Tear down the call: close the socket, stop the mic, release audio. Idempotent. Call in `onDestroy`. */
+  endCall: () => void;
+  /** Svelte readable store of the last transport/pipeline error, or `undefined`. Read with `$error`. */
+  error: Readable<Error | undefined>;
+  /** Svelte readable store of the live assistant text for the in-flight turn (grows via deltas; finalized on done). Read with `$interimTranscript`. */
+  interimTranscript: Readable<string>;
+  /** Svelte readable store: `true` while the mic is muted. Read with `$isMuted`. */
+  isMuted: Readable<boolean>;
+  /** Send a typed turn (no audio) — a text message spoken back by the agent. */
+  sendText: (text: string) => void;
+  /** Open the mic, connect the socket, and start the conversation. Idempotent while active. */
+  startCall: () => Promise<void>;
+  /** Svelte readable store of the current call lifecycle. Read with `$status`. */
+  status: Readable<VoiceStatus>;
+  /** Mute/unmute the microphone. Returns the new muted state. */
+  toggleMute: () => boolean;
+  /** Svelte readable store of the last finalized user utterance (STT result). Read with `$transcript`. */
+  transcript: Readable<string>;
+}
+/**
+ * A first-class voice-call surface for a voice-enabled agent: it opens a
+ * WebSocket to the agent's `VoiceSessionDO`, captures mic audio as 16 kHz PCM,
+ * streams the agent's synthesized speech back through the browser's audio output,
+ * and mirrors the call lifecycle (`status`, `transcript`, `interimTranscript`,
+ * `audioLevel`) to Svelte readable stores you read with `$`. Pass the generated
+ * `api.agents.<name>Voice` reference (never a string), matching `agentChat`'s
+ * reference-passing style. The Svelte counterpart to React's `useVoiceAgent`,
+ * re-expressed as stores; the per-call connection lives in a closure variable (a
+ * handle is created once per component, so no store-of-store indirection is
+ * needed).
+ *
+ * v1 transport is plain binary WebSocket frames with push-to-talk / silence-timer
+ * turn detection and client-side RMS barge-in. The heavy Web Audio capture and
+ * playback subsystems are injectable (`createMicrophone` / `createSpeaker` /
+ * `createSocket`) so the handle is drivable outside a browser.
+ *
+ * There is no auto-dispose in Svelte — call `endCall` in `onDestroy`
+ * (`onDestroy(handle.endCall)`) to tear the call down if the component unmounts
+ * mid-call.
+ *
+ * Pass `client` explicitly, or omit it to resolve the ambient client published by
+ * `setLunoraClient`.
+ */
+declare function voiceAgent(options: VoiceAgentOptions): VoiceAgentHandle;
+declare function voiceAgent(client: LunoraClient, options: VoiceAgentOptions): VoiceAgentHandle;
+export { type ActionHandle, type AgentApi, type AgentApprovalGrant, type AgentChatApi, type AgentChatHandle, type AgentChatMessage, type AgentChatOptions, type AgentHandle, type AgentLiveEvent, type AgentOptions, type AgentProgressEvent, type AgentStateApi, type AgentStateHandle, type AgentStateOptions, type AgentThreadRecord, type AgentThreadStatus, type AgentTokenDelta, type AgentToolEvent, type AgentToolEventsApi, type AgentToolEventsHandle, type AgentToolEventsOptions, type AuthGateStore, type AuthStore, type ConnectionStatusStore, type FlagValue, type HeartbeatReference, type InfiniteQueryHandle, type InfiniteQueryOptions, type ListPresentReference, type LiveTopicState, type MutationHandle, type MutatorHandleStore, type PageItemOf, type PaginatedArgs, type PaginatedQueryHandle, type PaginatedQueryOptions, type PresenceHandle, type PresenceOptions, type QueryStore, type QueryStoreOptions, type RateLimitHandle, type RateLimitOptions, type ReactiveArgs, type ReactivePaginatedArgs, type StreamHandle, type StreamStatus, type StreamStoreOptions, type SubscriptionHandle, type SubscriptionStoreOptions, type VoiceAgentHandle, type VoiceAgentOptions, type VoiceAudioFormat, type VoiceReference, type VoiceStatus, action, agent, agentChat, agentState, agentToolEvents, auth, authGate, connectionStatus, flag, flags,
+/**
+ * Svelte adapter for Lunora (`@lunora/svelte`).
+ *
+ * Thin, idiomatic glue over the framework-neutral `@lunora/client` (no React):
+ * live readable stores you read with `$store`, an optimistic mutation helper,
+ * and the reactive-loader handoff (`hydratePreloaded`). The contract mirrors
+ * `@lunora/react`, re-expressed in Svelte stores: `setLunoraClient` /
+ * `getLunoraClient` are the context provider/consumer; `query` is a live
+ * readable store (React's `useQuery`); `mutation` is an optimistic
+ * `{ data, error, pending, mutate, reset }` (React's `useMutation`); and
+ * `hydratePreloaded` is the SSR-seed-to-live-store handoff (React's
+ * `usePreloadedQuery`).
+ *
+ * The package is plain `.ts` over stores — no `.svelte` component compiler is
+ * required to build or test it.
+ *
+ * Server-side preload helpers (`createServerClient`, `preloadQuery`) live in the
+ * socket-free `@lunora/svelte/server` entry (a re-export of `@lunora/client/ssr`, the
+ * framework-neutral server contract) — import them there in your SvelteKit
+ * `+page.ts` / `+layout.ts` load.
+ */
+getLunoraClient, hydratePreloaded, infiniteQuery, liveTopic, mutation, mutator, paginatedQuery, presence, query, rateLimit,
+/**
+ * Svelte adapter for Lunora (`@lunora/svelte`).
+ *
+ * Thin, idiomatic glue over the framework-neutral `@lunora/client` (no React):
+ * live readable stores you read with `$store`, an optimistic mutation helper,
+ * and the reactive-loader handoff (`hydratePreloaded`). The contract mirrors
+ * `@lunora/react`, re-expressed in Svelte stores: `setLunoraClient` /
+ * `getLunoraClient` are the context provider/consumer; `query` is a live
+ * readable store (React's `useQuery`); `mutation` is an optimistic
+ * `{ data, error, pending, mutate, reset }` (React's `useMutation`); and
+ * `hydratePreloaded` is the SSR-seed-to-live-store handoff (React's
+ * `usePreloadedQuery`).
+ *
+ * The package is plain `.ts` over stores — no `.svelte` component compiler is
+ * required to build or test it.
+ *
+ * Server-side preload helpers (`createServerClient`, `preloadQuery`) live in the
+ * socket-free `@lunora/svelte/server` entry (a re-export of `@lunora/client/ssr`, the
+ * framework-neutral server contract) — import them there in your SvelteKit
+ * `+page.ts` / `+layout.ts` load.
+ */
+setLunoraClient, stream, subscription, voiceAgent };