@lunora/vue 1.0.0-alpha.28 → 1.0.0-alpha.280

package/dist/index.d.mts

@@ -1,184 +1,793 @@
-import { Component, Ref, InjectionKey, App, DeepReadonly, MaybeRefOrGetter, ComputedRef, ShallowRef } from 'vue';
-import { Preloaded, LunoraClient, User, ConnectionStatus, FunctionReference, ReturnOf, ArgsOf, MutationCallOptions, MutatorHandle } from '@lunora/client';
-export type { ArgsOf, FunctionReference, LunoraClient, MutationCallOptions, MutatorHandle, MutatorTransaction, OptimisticLocalStore, OptimisticUpdate, Preloaded, ReturnOf, Unsubscribe, User } from '@lunora/client';
+import { Component, Ref, InjectionKey, App, MaybeRefOrGetter, ComputedRef, DeepReadonly, ShallowRef } from 'vue';
+import { Preloaded, SubscriptionErrorCallback, LunoraClient, FunctionReference, ArgsOf, ActionCallOptions, ReturnOf, User, ConnectionStatus, LiveTopicOptions, LiveStreamSubscribeError, LiveTopicRef, MutationCallOptions, OnlineOnlyOption, MutatorHandle, SubscriptionError } from '@lunora/client';
+export type { ArgsOf, FunctionReference, LunoraClient, MutationCallOptions, MutatorHandle, MutatorTransaction, OptimisticLocalStore, OptimisticUpdate, Preloaded, ReturnOf, SubscriptionError, SubscriptionErrorCallback, Unsubscribe, User } from '@lunora/client';
+import { AuthStatus } from '@lunora/client/auth';
 import { PaginationStatus } from '@lunora/client/pagination';
 export type { PaginationResult, PaginationStatus } from '@lunora/client/pagination';
 import { RateLimitStatus, RateLimitConfig } from '@lunora/ratelimit';
 /**
-* Render the default slot only after auth has settled and a token + user are
-* both present. Hides the slot on first render and when signed out.
-*/
+ * Render the default slot once authentication has settled in the caller's
+ * favour — a credential is held and nothing has contradicted it.
+ *
+ * Gated on {@link isAuthenticatedStatus}, the shared contract in
+ * `@lunora/client/auth`, not on `user !== null`: an unreachable identity
+ * endpoint leaves `user` at `null` while the credential is still perfectly
+ * valid, and requiring a user record there hid the whole app behind
+ * `AuthLoading` for the length of an offline session.
+ */
 declare const Authenticated: Component;
 /**
-* Render the default slot only when auth has settled and no token is present
-* (the signed-out state). Hidden while the user is still loading.
-*/
+ * Render the default slot only when authentication has settled and there is no
+ * session — no credential, or the server answered that the credential has none.
+ */
 declare const Unauthenticated: Component;
 /**
-* Render the default slot while authentication is still in progress — token is
-* set but `getCurrentUser()` has not yet resolved.
-*/
+ * Render the default slot while authentication is still in progress — a
+ * credential is held and the first identity resolve has not come back yet.
+ */
 declare const AuthLoading: Component;
 /**
-* Hydrate a query from a {@link Preloaded} token produced by `preloadQuery`
-* during SSR, then keep it live — the Vue half of PLAN4's reactive-loader
-* handoff.
-*
-* The returned `ref` is seeded **synchronously** from `preloaded.value`, so the
-* very first read (during hydration) shows the server value: no loading flash,
-* no hydration mismatch. After seeding it opens a WebSocket subscription on the
-* same `(functionPath, args, shardKey)` the SSR loader used, so every later
-* server delta updates the ref exactly like `useQuery`.
-*
-* The subscription tears down with the surrounding effect scope (component
-* unmount or `effectScope().stop()`), inherited from `subscribeToQuery`.
-*/
-declare const hydratePreloaded: <T>(preloaded: Preloaded<T>) => Ref<T | undefined>;
-/**
-* Injection key carrying the {@link LunoraClient} down the component tree.
-* Exported so advanced consumers can inject it by hand; most apps use
-* {@link createLunora} or {@link provideLunora}.
-*/
+ * Hydrate a query from a {@link Preloaded} token produced by `preloadQuery`
+ * during SSR, then keep it live — the Vue half of PLAN4's reactive-loader
+ * handoff.
+ *
+ * The returned `ref` is seeded **synchronously** from `preloaded.value`, so the
+ * very first read (during hydration) shows the server value: no loading flash,
+ * no hydration mismatch. After seeding it opens a WebSocket subscription on the
+ * same `(functionPath, args, shardKey)` the SSR loader used, so every later
+ * server delta updates the ref exactly like `useQuery`.
+ *
+ * The subscription tears down with the surrounding effect scope (component
+ * unmount or `effectScope().stop()`), inherited from `subscribeToQuery`.
+ *
+ * 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
+ * ref keeps rendering the SSR snapshot as if it were live.
+ *
+ * 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` on the client (mounted
+ * then or later) stops using it and holds `undefined` until the live value
+ * arrives — matching `@lunora/react`'s `usePreloadedQuery`. The ref is typed
+ * `Ref<T | undefined>` like `useQuery`, so guard for that window.
+ */
+declare const hydratePreloaded: <T>(preloaded: Preloaded<T>, options?: {
+  onError?: SubscriptionErrorCallback;
+}) => Ref<T | undefined>;
+/**
+ * Injection key carrying the {@link LunoraClient} down the component tree.
+ * Exported so advanced consumers can inject it by hand; most apps use
+ * {@link createLunora} or {@link provideLunora}.
+ */
 declare const LUNORA_INJECTION_KEY: InjectionKey<LunoraClient>;
 /**
-* Vue plugin form: `app.use(createLunora(client))`. Mirrors the React
-* `LunoraProvider` — establishes the single app-wide client every composable
-* resolves through {@link useLunora}.
-*
-* The client is framework-neutral (`@lunora/client`): it owns the WebSocket
-* transport, subscription registry, offline queue, and delta-merge. This plugin
-* only wires it into Vue's `provide`/`inject` graph (read it with
-* {@link useLunora}); it adds no React, no store, and no extra reactivity layer.
-*/
+ * Vue plugin form: `app.use(createLunora(client))`. Mirrors the React
+ * `LunoraProvider` — establishes the single app-wide client every composable
+ * resolves through {@link useLunora}.
+ *
+ * The client is framework-neutral (`@lunora/client`): it owns the WebSocket
+ * transport, subscription registry, offline queue, and delta-merge. This plugin
+ * only wires it into Vue's `provide`/`inject` graph (read it with
+ * {@link useLunora}); it adds no React, no store, and no extra reactivity layer.
+ */
 declare const createLunora: (client: LunoraClient) => {
   install: (app: App) => void;
 };
 /**
-* Composition-API form: call inside a parent component's `setup()` to provide
-* the client to its subtree. The counterpart to `app.use(createLunora(client))`
-* when you'd rather scope the client to a subtree than the whole app. Must run
-* synchronously inside `setup()` (Vue's `provide` constraint).
-*/
+ * Composition-API form: call inside a parent component's `setup()` to provide
+ * the client to its subtree. The counterpart to `app.use(createLunora(client))`
+ * when you'd rather scope the client to a subtree than the whole app. Must run
+ * synchronously inside `setup()` (Vue's `provide` constraint).
+ */
 declare const provideLunora: (client: LunoraClient) => void;
 /**
-* Read the {@link LunoraClient} from the nearest provider — the Vue counterpart
-* to `@lunora/react`/`@lunora/solid`'s `useLunora`. Throws with a clear message
-* when called outside a `createLunora`/`provideLunora` scope so the failure
-* points at the missing provider rather than a later `undefined` deref.
-*/
+ * Read the {@link LunoraClient} from the nearest provider — the Vue counterpart
+ * to `@lunora/react`/`@lunora/solid`'s `useLunora`. Throws with a clear message
+ * when called outside a `createLunora`/`provideLunora` scope so the failure
+ * points at the missing provider rather than a later `undefined` deref.
+ */
 declare const useLunora: () => LunoraClient;
 /** Options shared by the live-query composables. */
 interface UseQueryOptions {
+  /**
+   * Called when the server pushes a subscription-scoped error (an RLS denial, a
+   * query that starts failing server-side). Without a handler such an error has
+   * nowhere to go and the ref simply freezes at its last good value.
+   */
+  onError?: SubscriptionErrorCallback;
   /** Route to a specific shard when the target function is `.shardBy(...)`-partitioned. */
   shardKey?: string;
 }
+/**
+ * The reactive handle returned by {@link useAction} — the Vue counterpart to
+ * React's `useAction`, re-expressed with refs. The surface is identical across
+ * the Lunora adapters (`@lunora/solid`, `/svelte`): `data`/`error`/`pending`
+ * are refs you read in a template, and `call` is an awaitable that resolves with
+ * the server value (or rejects).
+ */
+interface ActionHandle<F extends FunctionReference> {
+  /** Invoke the action. Resolves with the server value; rejects on failure. */
+  call: (args: ArgsOf<F>, options?: ActionCallOptions) => Promise<ReturnOf<F>>;
+  /** The latest invocation's resolved value, or `undefined` before the first success. */
+  data: Ref<ReturnOf<F> | undefined>;
+  /** The latest invocation's error, or `undefined`. */
+  error: Ref<Error | undefined>;
+  /** `true` while ANY invocation from this handle is in flight (ref-counted, so overlapping calls compose). */
+  pending: Ref<boolean>;
+  /** Clear the latest `data`/`error` back to idle. */
+  reset: () => void;
+}
+/**
+ * Returns a reactive {@link ActionHandle} for the given action reference — the
+ * Vue equivalent of React's `useAction`.
+ *
+ * Actions were the one procedure kind with no adapter hook: `useQuery` and
+ * `useMutation` shipped in every adapter and nothing covered actions, so each
+ * app re-derived the same pending/error wrapper by hand.
+ *
+ * **Narrower than `useMutation` on purpose:** there are no `optimistic` /
+ * `optimisticUpdate` call options. 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. Offering the option would imply a rollback guarantee nothing can
+ * honour.
+ *
+ * `pending` is ref-counted across overlapping invocations of THIS handle, so it
+ * flips back to `false` only once every concurrent call has settled. That
+ * orchestration is the shared `createCallRunner` from `@lunora/client`; only the
+ * refs 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 so a
+ * transient error does not blank the view. `reset()` clears both; it does not
+ * cancel an in-flight call, whose result still lands.
+ */
+declare const useAction: <F extends FunctionReference>(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 Vue entry never pulls in the server-only `@lunora/agent` module graph
+ * (the adapter stays Vue + `@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 composable 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 UseAgentApi {
+  agents: {
+    agentThread: FunctionReference<"query", {
+      key: string;
+    }, Record<string, unknown> | undefined>;
+  };
+}
+interface UseAgentOptions {
+  /** The generated `api` — its `agents.agentThread` query drives live thread state. */
+  api: UseAgentApi;
+  /**
+   * 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 UseAgentResult.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 — and without reading `error` — such a
+   * failure is invisible and `thread` / `status` are cleared until a later frame arrives.
+   */
+  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 UseAgentOptions.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 — may be a plain value, `ref`, or getter (a reactive source re-subscribes). */
+  threadKey: MaybeRefOrGetter<string>;
+}
+interface UseAgentResult {
+  /**
+   * 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>;
+  /** The live thread subscription's last error, or `undefined`. */
+  error: Ref<Error | undefined>;
+  /** `true` while a `run` invocation is in flight. */
+  pending: Readonly<Ref<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. */
+  status: ComputedRef<AgentThreadStatus | undefined>;
+  /** The live thread record (status, `instanceId`, …), or `undefined` before it exists. */
+  thread: ComputedRef<AgentThreadRecord | undefined>;
+}
+/**
+ * A thin agent handle: live thread `status` plus `run` / `cancel`, without the
+ * chat message surface. Composes `useSubscription(api.agents.agentThread)` for
+ * live state and `useMutation` for the run/cancel writes — the Vue counterpart to
+ * React's `useAgent`, re-expressed with refs. For the full conversation surface
+ * (durable history + streaming + approvals) use `useAgentChat`.
+ *
+ * `run` and `cancel` stay generic over the app-defined mutations that wrap
+ * `ctx.agents.<name>.run` / `.cancel`, so the composable hard-codes no function
+ * names beyond the `agents:*` surface. `threadKey` may be reactive — a changing
+ * key re-subscribes to the new thread.
+ */
+declare const useAgent: (options: UseAgentOptions) => UseAgentResult;
+/**
+ * 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 Vue 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 UseAgentChatResult.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 `useAgentToolEvents`, ignored by {@link UseAgentChatResult.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 composable consumes only the token arm.
+ */
+type AgentTokenStreamReference = FunctionReference<"stream", {
+  key: string;
+}, AgentLiveEvent>;
+/**
+ * The `agents.*` reference surface the chat composable reads. A structural subset
+ * of the generated `api.agents`, so the whole generated `api` object is
+ * assignable.
+ */
+interface UseAgentChatApi {
+  agents: {
+    agentApprovalGrants: AgentApprovalGrantsReference;
+    agentDeclineSecret: AgentDeclineSecretReference;
+    agentMessages: AgentMessagesReference$1;
+    agentResolveApproval: AgentApprovalReference;
+    agentRevokeApprovalGrant: AgentRevokeApprovalGrantReference;
+    agentSupplySecret: AgentSupplySecretReference;
+    agentThread: AgentThreadReference;
+  };
+}
+interface UseAgentChatOptions {
+  /** The generated `api` — its `agents.*` surface provides history, thread state, and approval resolution. */
+  api: UseAgentChatApi;
+  /**
+   * 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 UseAgentChatResult.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 — and without reading `error` —
+   * such a failure is invisible and `messages` / `status` are cleared until a later frame arrives.
+   */
+  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 UseAgentChatOptions.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 UseAgentChatResult.streamingText}
+   * stays empty and the UI updates message-by-message from durable history.
+   */
+  stream?: AgentTokenStreamReference;
+  /** The thread to observe and continue — may be a plain value, `ref`, or getter (a reactive source re-subscribes). */
+  threadKey: MaybeRefOrGetter<string>;
+}
+interface UseAgentChatResult {
+  /** The tools approved for the rest of this thread, live. Empty until the grants subscription answers. */
+  approvalGrants: ComputedRef<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 UseAgentChatResult.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>;
+  /** The history, thread, or grants subscription's last error, or `undefined`. */
+  error: ComputedRef<Error | undefined>;
+  /** Durable thread history (oldest first) plus any un-acknowledged optimistic user turns. */
+  messages: ComputedRef<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. */
+  status: ComputedRef<AgentThreadStatus | undefined>;
+  /** The in-flight turn's streamed text — live-only, empty once the turn persists to `messages`. */
+  streamingText: ComputedRef<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 composable keeps no copy;
+   * a failure rethrows the original error.
+   */
+  supplySecret: (toolCallId: string, secret: string) => Promise<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 Vue counterpart to React's `useAgentChat`, re-expressed with refs.
+ *
+ * It composes the existing primitives rather than adding transport:
+ * `useSubscription(api.agents.agentMessages)` for durable history,
+ * `useSubscription(api.agents.agentThread)` for live status + the in-flight
+ * `instanceId`, {@link useStream} over an app token stream for in-flight deltas,
+ * and `useMutation` 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), consistent with the loop's
+ * replay-safe, live-only delta design.
+ */
+declare const useAgentChat: (options: UseAgentChatOptions) => UseAgentChatResult;
+/**
+ * The `agents.agentState` reference the composable subscribes to for the thread's
+ * live synced state. A structural subset of the generated `api.agents` surface
+ * (like `UseAgentApi` 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 composable's generic `T`, since codegen pins the reference
+ * return as an optional record (it never evaluates agent config).
+ */
+interface UseAgentStateApi {
+  agents: {
+    agentState: FunctionReference<"query", {
+      key: string;
+    }, Record<string, unknown> | undefined>;
+  };
+}
+interface UseAgentStateOptions {
+  /** The generated `api` — its `agents.agentState` query drives live thread state. */
+  api: UseAgentStateApi;
+  /** The thread whose synced state to observe — may be a plain value, `ref`, or getter (a reactive source re-subscribes). */
+  threadKey: MaybeRefOrGetter<string>;
+}
+interface UseAgentStateResult<T> {
+  /** The subscription error, if the live channel reported one. */
+  error: Ref<Error | undefined>;
+  /** The live synced state, or `undefined` before it is seeded/first pushed. */
+  state: ComputedRef<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 `useSubscription(api.agents.agentState, { key })`: 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 Vue counterpart to React's
+ * `useAgentState`, re-expressed with refs.
+ *
+ * Generic over the app's state shape (`useAgentState` with a `SupportState` type
+ * argument, 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 `extends` bound (not
+ * a bare unbounded type parameter) is required: this `.ts` file is parsed
+ * JSX-aware by the bundler, where an unbounded type-param arrow is ambiguous with
+ * a JSX element.
+ */
+declare const useAgentState: <T extends Record<string, unknown> = Record<string, unknown>>(options: UseAgentStateOptions) => UseAgentStateResult<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 composable consumes
+ * only the progress arm (`kind === "progress"`).
+ */
+type AgentLiveStreamReference = FunctionReference<"stream", {
+  key: string;
+}, AgentLiveEvent>;
+/**
+ * The `agents.*` reference surface the tool-events composable reads. A structural
+ * subset of the generated `api.agents`, so the whole generated `api` object is
+ * assignable.
+ */
+interface UseAgentToolEventsApi {
+  agents: {
+    agentMessages: AgentMessagesReference;
+  };
+}
+interface UseAgentToolEventsOptions {
+  /** The generated `api` — its `agents.agentMessages` query provides the durable tool lifecycle. */
+  api: UseAgentToolEventsApi;
+  /** History depth forwarded to `agents:agentMessages`. */
+  limit?: number;
+  /**
+   * Optional live event stream — the same app stream function `useAgentChat`
+   * 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 — may be a plain value, `ref`, or getter (a reactive source re-subscribes). */
+  threadKey: MaybeRefOrGetter<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 UseAgentToolEventsResult {
+  /**
+   * 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. Treat as derived, not identity-stable.
+   */
+  events: ComputedRef<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 Vue counterpart to React's
+ * `useAgentToolEvents`, re-expressed as a `computed`.
+ *
+ * It composes the existing primitives rather than adding transport:
+ * `useSubscription(api.agents.agentMessages)` for the durable lifecycle and
+ * {@link useStream} over the optional app event stream for ephemeral progress.
+ * 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 `useAgentChat`; this composable is the tool-observability slice.
+ */
+declare const useAgentToolEvents: (options: UseAgentToolEventsOptions) => UseAgentToolEventsResult;
 interface UseAuthResult {
   setToken: (token: string | null) => void;
+  /**
+   * 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: DeepReadonly<Ref<AuthStatus>>;
   token: DeepReadonly<Ref<string | null>>;
   user: DeepReadonly<Ref<User | null>>;
 }
 /**
-* Token + identity plumbing for Vue. `token` is a readonly ref tracking the
-* client's auth token; `user` is a readonly ref resolved from `getCurrentUser()`
-* whenever the token changes. `setToken(jwt)` after sign-in makes subsequent
-* RPC calls carry the `Authorization` header.
-*
-* Multiple `useAuth` instances within the same effect scope share a single
-* per-client identity store (from `@lunora/client/auth`) — a `setToken` from
-* one component re-renders every watcher with the freshly-resolved user.
-*/
+ * Token + identity plumbing for Vue. `token` is a readonly ref tracking the
+ * client's auth token; `user` is a readonly ref resolved from `getCurrentUser()`
+ * whenever the token changes. `setToken(jwt)` after sign-in makes subsequent
+ * RPC calls carry the `Authorization` header.
+ *
+ * Multiple `useAuth` instances within the same effect scope share a single
+ * per-client identity store (from `@lunora/client/auth`) — a `setToken` from
+ * one component re-renders every watcher with the freshly-resolved user.
+ *
+ * Both subscribes are client-only, for the same reason as `useFlags`: this
+ * runs synchronously inside `setup()` during `renderToString`, and that render
+ * scope is never stopped, so `onScopeDispose` never fires. For the identity
+ * subscribe that is not just a stray listener — the 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
+ * refs still hold the client's current values; live updates start at hydration.
+ */
 declare const useAuth: () => UseAuthResult;
 /**
-* Reactive view of the client's aggregate live-socket status across all shard
-* connections, exposed as a read-only `ref`. The value transitions through
-* `idle` → `connecting` → `connected` → `offline` as sockets open and drop —
-* use it to drive a connection indicator so an operator can tell a healthy live
-* channel from a silently-dropped one. The Vue-idiomatic equivalent of
-* `@lunora/react`'s `useConnectionStatus`.
-*
-* Teardown is wired to the active effect scope (`onScopeDispose`), so the
-* status listener is released on component unmount (or `effectScope().stop()`).
-* Call inside `setup()` / an active effect scope.
-*/
+ * Reactive view of the client's aggregate live-socket status across all shard
+ * connections, exposed as a read-only `ref`. The value transitions through
+ * `idle` → `connecting` → `connected` → `offline` as sockets open and drop —
+ * use it to drive a connection indicator so an operator can tell a healthy live
+ * channel from a silently-dropped one. The Vue-idiomatic equivalent of
+ * `@lunora/react`'s `useConnectionStatus`.
+ *
+ * Teardown is wired to the active effect scope (`onScopeDispose`), so the
+ * status listener is released on component unmount (or `effectScope().stop()`).
+ * Call inside `setup()` / an active effect scope.
+ *
+ * Client-only, for the same reason as `useFlags`: this runs synchronously
+ * inside `setup()` during `renderToString`, and that render scope is never
+ * stopped — `onScopeDispose` therefore never fires and an unguarded listener
+ * would stay registered on the client for the lifetime of the server process,
+ * one per rendered request. The ref still holds the client's current status,
+ * which is what the SSR HTML should show; live updates start at hydration.
+ */
 declare const useConnectionStatus: () => Readonly<Ref<ConnectionStatus>>;
-/** 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;
 /**
-* Subscribe to a single feature flag, live over Lunora's WebSocket.
-*
-* The returned `ref` holds `defaultValue` until the first evaluation lands, then
-* the server's resolved value — re-pushed 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 `useFlag("dark", false)` reads a boolean
-* and `useFlag("hero", "control")` a string.
-*
-* `key` and `context` may be plain values, `ref`s, or getters: passing a reactive
-* source makes the subscription reactive — when it changes the old subscription
-* is torn down and a fresh one opens. `context` supplies a per-call targeting
-* context merged on top of the app's default `identify` targeting key.
-*
-* Evaluation runs through whatever OpenFeature provider the app wired in
-* `lunora/flags.ts`; the read never throws — a provider error resolves the
-* default (the same fail-open contract as server-side `ctx.flags`). Call inside
-* `setup()` (or any active effect scope); the subscription tears down on unmount.
-*/
-declare const useFlag: <T extends FlagValue>(key: MaybeRefOrGetter<string>, defaultValue: T, context?: MaybeRefOrGetter<FlagContext | undefined>) => Readonly<Ref<T>>;
-/**
-* Subscribe to several feature flags at once, live over Lunora's WebSocket.
-*
-* Pass a record of `key → defaultValue`; each flag's kind is inferred from its
-* default, and the returned `ref` holds the same-shaped record with resolved
-* values (the defaults until each evaluation lands). A single `context` applies
-* to every flag and may be reactive. This is the batched form of {@link useFlag}
-* — one watcher manages one subscription per key.
-*/
-declare const useFlags: <T extends Record<string, FlagValue>>(flags: T, context?: MaybeRefOrGetter<FlagContext | undefined>) => Readonly<Ref<T>>;
-/**
-* The reactive handle returned by {@link useMutation} — the Vue counterpart to
-* React's `useMutation`, re-expressed with refs. The surface is identical across
-* the Lunora adapters (`@lunora/solid`, `/svelte`): `data`/`error`/`pending` are
-* refs you read in a template, `mutate` is an awaitable that resolves with the
-* server value (or rejects). Per-call `optimistic` / `optimisticUpdate` options
-* pass straight through to `client.mutation`.
-*/
+ * Subscribe to a single feature flag, live over Lunora's WebSocket.
+ *
+ * The returned `ref` holds `defaultValue` until the first evaluation lands, then
+ * the server's resolved value — re-pushed 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 `useFlag("dark", false)` reads a boolean
+ * and `useFlag("hero", "control")` a string.
+ *
+ * `key` may be a plain value, a `ref`, or a getter: passing a reactive source
+ * makes the subscription reactive — when it changes the old subscription is torn
+ * down and a fresh one opens.
+ *
+ * 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.
+ *
+ * Evaluation runs through whatever OpenFeature provider the app wired in
+ * `lunora/flags.ts`; the read never throws — a provider error resolves the
+ * default (the same fail-open contract as server-side `ctx.flags`) — both an
+ * attach throw and a provider error pushed mid-session. Call inside `setup()`
+ * (or any active effect scope); the subscription tears down on unmount. During
+ * SSR no subscription opens at all and the ref stays at `defaultValue`.
+ */
+declare const useFlag: <T extends FlagValue>(key: MaybeRefOrGetter<string>, defaultValue: T) => Readonly<Ref<T>>;
+/**
+ * Subscribe to several feature flags at once, live over Lunora's WebSocket.
+ *
+ * Pass a record of `key → defaultValue`; each flag's kind is inferred from its
+ * default, and the returned `ref` holds the same-shaped record with resolved
+ * values (the defaults until each evaluation lands). This is the batched form of
+ * {@link useFlag} — one subscription per key, torn down together when the
+ * enclosing effect scope stops. Like {@link useFlag} it evaluates under the
+ * socket's server-verified identity only. The flag set is fixed for the
+ * composable's lifetime, so nothing here is reactive.
+ */
+declare const useFlags: <T extends Record<string, FlagValue>>(flags: T) => Readonly<Ref<T>>;
+/** The connection-level fields: every {@link LiveTopicOptions} field except the two callbacks. */
+type ConnectionFields = Omit<LiveTopicOptions, "onError" | "onEvent">;
+/**
+ * Options for {@link useLiveTopic}. Each connection field may be a plain value, a
+ * `ref`, or a getter, so a reactive `shardKey` or `headers` re-subscribes. The callbacks
+ * are plain functions: a getter would be called by `toValue`, so they are never wrapped.
+ */
+type UseLiveTopicOptions<Payload = unknown> = Pick<LiveTopicOptions<Payload>, "onError" | "onEvent"> & { [K in keyof ConnectionFields]: MaybeRefOrGetter<ConnectionFields[K]>; };
+interface UseLiveTopicResult<Payload = unknown> {
+  /** Set when the shard refuses the subscription (403, 409, 429 and similar). */
+  error: ShallowRef<LiveStreamSubscribeError | undefined>;
+  /** The last payload delivered on the topic, or `undefined` until the first event. */
+  lastEvent: ShallowRef<Payload | undefined>;
+}
+/**
+ * `useLiveTopic` — follow one live topic of a `defineLiveStream` for the life of
+ * the calling component's effect scope. Pass the reference `_generated/live.ts` hands
+ * out (`live.posts.post({ postId })`), as a value, a `ref` or a getter: the stream's
+ * route is resolved against the injected `LunoraClient`, and `lastEvent` and `onEvent`
+ * are typed by the payload the topic declares.
+ *
+ * A lifecycle wrapper over `subscribeLiveTopic`: the connection is shared by URL,
+ * so several composables on one page still open one stream. It subscribes on
+ * setup, unsubscribes when the scope disposes, and resubscribes when the reference
+ * or a reactive connection field changes. Callbacks are read at call time, so they
+ * never resubscribe.
+ *
+ * Client-only: nothing opens during SSR, and the refs stay at their initial values there.
+ */
+declare const useLiveTopic: <Payload>(topic: MaybeRefOrGetter<LiveTopicRef<Payload>>, options?: UseLiveTopicOptions<Payload>) => UseLiveTopicResult<Payload>;
+/**
+ * The reactive handle returned by {@link useMutation} — the Vue counterpart to
+ * React's `useMutation`, re-expressed with refs. The surface is identical across
+ * the Lunora adapters (`@lunora/solid`, `/svelte`): `data`/`error`/`pending` are
+ * refs you read in a template, `mutate` is an awaitable that resolves with the
+ * server value (or rejects). Per-call `optimistic` / `optimisticUpdate` options
+ * pass straight through to `client.mutation`.
+ */
 interface MutationHandle<F extends FunctionReference> {
   /** The latest invocation's resolved value, or `undefined` before the first success. */
   data: Ref<ReturnOf<F> | undefined>;
   /** The latest invocation's error, or `undefined`. */
   error: Ref<Error | undefined>;
   /** Invoke the mutation. Resolves with the server value; rejects on failure. */
-  mutate: (args: ArgsOf<F>, options?: MutationCallOptions<unknown, unknown, ArgsOf<F>>) => Promise<ReturnOf<F>>;
+  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). */
   pending: Ref<boolean>;
   /** Clear the latest `data`/`error` back to idle. */
   reset: () => void;
 }
 /**
-* Returns a reactive {@link MutationHandle} for the given mutation reference —
-* the Vue equivalent of React's `useMutation`.
-*
-* Optimistic updates stay client-owned: the `optimistic` / `optimisticUpdate`
-* call options pass straight through to `client.mutation`, which applies and
-* rolls them back against the Lunora subscription cache (Convex parity).
-*
-* `pending` is ref-counted across overlapping invocations of THIS handle, so it
-* flips back to `false` only once every concurrent call has settled. The
-* ref-counted pending + error-normalize orchestration is the shared
-* `createMutationRunner` from `@lunora/client`; only the refs are
-* adapter-specific.
-*/
+ * Returns a reactive {@link MutationHandle} for the given mutation reference —
+ * the Vue equivalent of React's `useMutation`.
+ *
+ * Optimistic updates stay client-owned: the `optimistic` / `optimisticUpdate`
+ * call options pass straight through to `client.mutation`, which applies and
+ * rolls them back against the Lunora subscription cache (Convex parity).
+ *
+ * `pending` is ref-counted across overlapping invocations of THIS handle, so it
+ * flips back to `false` only once every concurrent call has settled. The
+ * ref-counted pending + error-normalize orchestration is the shared
+ * `createCallRunner` from `@lunora/client`; only the refs 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.
+ */
 declare const useMutation: <F extends FunctionReference>(function_: F) => MutationHandle<F>;
 /**
-* The reactive handle returned by {@link useMutator} — the Vue counterpart to
-* `@lunora/react`'s `useMutator`, re-expressed with refs. The surface is
-* identical across the Lunora adapters (`@lunora/solid`, `/svelte`):
-* `error`/`isError`/`pending` are refs you read in a template and `mutate` is an
-* awaitable that resolves once the write is persisted (or rejects).
-*/
+ * The reactive handle returned by {@link useMutator} — the Vue counterpart to
+ * `@lunora/react`'s `useMutator`, re-expressed with refs. The surface is
+ * identical across the Lunora adapters (`@lunora/solid`, `/svelte`):
+ * `error`/`isError`/`pending` are refs you read in a template and `mutate` is an
+ * awaitable that resolves once the write is persisted (or rejects).
+ */
 interface MutatorHook<TArgs> {
   /** The latest invocation's error, or `undefined`. */
   error: Ref<Error | undefined>;
@@ -192,18 +801,18 @@ interface MutatorHook<TArgs> {
   reset: () => void;
 }
 /**
-* Ergonomic `{ mutate, pending, error, isError, reset }` wrapper over a bound
-* custom-mutator handle from `@lunora/db`'s `bindMutators` — the Vue 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 composable only surfaces reactive state for the in-flight/error
-* lifecycle. Reads stay on the existing TanStack `useLiveQuery`; no new query
-* composable 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 Vue 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 composable only surfaces reactive state for the in-flight/error
+ * lifecycle. Reads stay on the existing TanStack `useLiveQuery`; no new query
+ * composable is needed.
+ *
+ * `pending` is ref-counted across overlapping invocations of THIS handle, so it
+ * clears only once every concurrent call has settled.
+ */
 declare const useMutator: <TArgs = Record<string, unknown>>(handle: MutatorHandle<TArgs>) => MutatorHook<TArgs>;
 /** The args a paginated query exposes minus the framework-supplied page cursor. */
 type PaginatedArgs<F extends FunctionReference> = Omit<ArgsOf<F>, "paginationOpts">;
@@ -214,9 +823,18 @@ type PageItemOf<F extends FunctionReference> = ReturnOf<F> extends {
 interface UsePaginatedQueryOptions {
   /** 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` ref). */
+  onError?: SubscriptionErrorCallback;
   shardKey?: string;
 }
 interface UsePaginatedQueryResult<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 change.
+   */
+  error: Ref<SubscriptionError | undefined>;
   /** `true` while the first page or a `loadMore` page is in flight. */
   isLoading: Ref<boolean>;
   /** Request the next page. A no-op unless `status === "CanLoadMore"`. */
@@ -226,31 +844,35 @@ interface UsePaginatedQueryResult<T> {
   status: Ref<PaginationStatus>;
 }
 /**
-* Subscribe to a reactively-paginated query and grow the feed page by page.
-*
-* The query function must accept a `paginationOpts: { numItems, cursor,
-* endCursor }` arg and return a `PaginationResult`. Pages are tracked as an
-* ordered list of stable boundary cursors; each loaded page is a live
-* subscription over a FIXED `(lower, upper]` range. Inserting or deleting a row
-* grows/shrinks the affected page without duplicating or skipping rows across
-* boundaries.
-*
-* `loadMore` appends the next page off the open-ended tail's `continueCursor`;
-* it is a no-op unless `status === "CanLoadMore"`. Background split/join
-* maintenance keeps page sizes near `initialNumItems` as edits accumulate.
-*
-* Changing `fn`, the base `args`, `initialNumItems`, or `shardKey` resets the
-* feed to its first page.
-*
-* Call inside `setup()` (or any active effect scope).
-*/
+ * Subscribe to a reactively-paginated query and grow the feed page by page.
+ *
+ * The query function must accept a `paginationOpts: { numItems, cursor,
+ * endCursor }` arg and return a `PaginationResult`. Pages are tracked as an
+ * ordered list of stable boundary cursors; each loaded page is a live
+ * subscription over a FIXED `(lower, upper]` range. Inserting or deleting a row
+ * grows/shrinks the affected page without duplicating or skipping rows across
+ * boundaries.
+ *
+ * `loadMore` appends the next page off the open-ended tail's `continueCursor`;
+ * it is a no-op unless `status === "CanLoadMore"`. Background split/join
+ * maintenance keeps page sizes near `initialNumItems` as edits accumulate.
+ *
+ * Changing `fn`, the base `args`, `initialNumItems`, or `shardKey` resets the
+ * feed to its first page.
+ *
+ * Call inside `setup()` (or any active effect scope).
+ */
 declare const usePaginatedQuery: <F extends FunctionReference>(function_: F, args: MaybeRefOrGetter<"skip" | PaginatedArgs<F>>, options: UsePaginatedQueryOptions) => UsePaginatedQueryResult<PageItemOf<F>>;
 interface UseInfiniteQueryOptions {
   /** 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` ref). */
+  onError?: SubscriptionErrorCallback;
   shardKey?: string;
 }
 interface UseInfiniteQueryResult<T> {
+  /** The last page subscription error, or `undefined` — see `UsePaginatedQueryResult.error`. */
+  error: Ref<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. */
@@ -264,37 +886,37 @@ interface UseInfiniteQueryResult<T> {
   status: Ref<PaginationStatus>;
 }
 /**
-* Subscribe to a reactively-paginated query and expose its pages discretely.
-*
-* Shares `usePaginatedQuery`'s reactive-pagination engine but keeps each page
-* as its own inner array rather than flattening them, and adds the
-* TanStack-Query-style `fetchNextPage` / `hasNextPage` / `isFetchingNextPage`
-* shape.
-*
-* Call inside `setup()` (or any active effect scope).
-*/
+ * Subscribe to a reactively-paginated query and expose its pages discretely.
+ *
+ * Shares `usePaginatedQuery`'s reactive-pagination engine but keeps each page
+ * as its own inner array rather than flattening them, and adds the
+ * TanStack-Query-style `fetchNextPage` / `hasNextPage` / `isFetchingNextPage`
+ * shape.
+ *
+ * Call inside `setup()` (or any active effect scope).
+ */
 declare const useInfiniteQuery: <F extends FunctionReference>(function_: F, args: MaybeRefOrGetter<"skip" | PaginatedArgs<F>>, options: UseInfiniteQueryOptions) => UseInfiniteQueryResult<PageItemOf<F>>;
 /**
-* `usePresence` — collaborative-awareness composable, the client half of the
-* `@lunora/server` `definePresence` preset.
-*
-* Drives the heartbeat mutation (on mount, interval, and tab re-focus) and
-* subscribes to the live `listPresent` query for the given room.
-*
-* Call inside `setup()` (or any active effect scope).
-*/
-/**
-* A heartbeat mutation reference: takes `{ roomId, sessionId, data? }`.
-*/
+ * `usePresence` — collaborative-awareness composable, the client half of the
+ * `@lunora/server` `definePresence` preset.
+ *
+ * Drives the heartbeat mutation (on mount, interval, and tab re-focus) and
+ * subscribes to the live `listPresent` query for the given room.
+ *
+ * Call inside `setup()` (or any active effect scope).
+ */
+/**
+ * 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;
 }>;
@@ -308,14 +930,22 @@ interface UsePresenceOptions<H extends HeartbeatReference, L extends ListPresent
   /** 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` is cleared until a later frame arrives.
+   */
+  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 UsePresenceResult<L extends ListPresentReference> {
+  /** The `listPresent` subscription's last error, or `undefined`. */
+  error: ShallowRef<SubscriptionError | undefined>;
   /** The present members for the room. `undefined` until the first push. */
   present: ShallowRef<ReturnOf<L> | undefined>;
   /** This mount's session id (generated when not supplied). */
@@ -325,51 +955,58 @@ interface UsePresenceResult<L extends ListPresentReference> {
 }
 declare const usePresence: <H extends HeartbeatReference, L extends ListPresentReference>(roomId: string, options: UsePresenceOptions<H, L>) => UsePresenceResult<L>;
 /**
-* Open a live subscription against `client` for FIXED args and stream its values
-* into a `ref`. The low-level primitive behind `hydratePreloaded` (whose args
-* come from an immutable `Preloaded` token and never change); {@link useQuery}
-* handles the reactive-args case separately.
-*
-* `client.subscribe` already dedupes by `(functionPath, args, shardKey)` and
-* replays the last value synchronously, so multiple consumers of the same query
-* ride one server-side registration. `seed` sets the ref's value synchronously
-* before the subscription attaches, so the first read shows the SSR value with
-* no loading flash.
-*
-* Teardown is wired to the active effect scope (`onScopeDispose`), so it fires
-* on component unmount or `effectScope().stop()`. Call it inside `setup()` / an
-* effect scope (as `hydratePreloaded` does); outside any scope there is nothing
-* to own the subscription, so it would leak until the process exits — the
-* `getCurrentScope` guard only avoids throwing, it does not auto-clean.
-*/
+ * Open a live subscription against `client` for FIXED args and stream its values
+ * into a `ref`. The low-level primitive behind `hydratePreloaded` (whose args
+ * come from an immutable `Preloaded` token and never change); {@link useQuery}
+ * handles the reactive-args case separately.
+ *
+ * `client.subscribe` already dedupes by `(functionPath, args, shardKey)` and
+ * replays the last value synchronously, so multiple consumers of the same query
+ * ride one server-side registration. `seed` sets the ref's value synchronously
+ * before the subscription attaches, so the first read shows the SSR value with
+ * no loading flash. `onError` receives a subscription-scoped error the server
+ * pushes (a session expiry, an RLS denial); without it the ref keeps rendering
+ * the seed as if it were live.
+ *
+ * Teardown is wired to the active effect scope (`onScopeDispose`), so it fires
+ * on component unmount or `effectScope().stop()`. Call it inside `setup()` / an
+ * effect scope (as `hydratePreloaded` does); outside any scope there is nothing
+ * to own the subscription, so it would leak until the process exits — the
+ * `getCurrentScope` guard only avoids throwing, it does not auto-clean.
+ */
 declare const subscribeToQuery: <F extends FunctionReference, T = ReturnOf<F>>(client: LunoraClient, function_: F, args: ArgsOf<F>, options?: {
+  onError?: SubscriptionErrorCallback;
   seed?: T;
   shardKey?: string;
 }) => Ref<T | undefined>;
 /**
-* Subscribe to a server query and expose its latest value as a `ref`.
-*
-* The returned ref is `undefined` until the first server response lands, then
-* updates on every delta the server pushes — the Vue-idiomatic equivalent of
-* React's `useQuery`. `args` may be a plain value, a `ref`, or a getter: passing
-* a reactive source makes the subscription reactive — when the args change the
-* old subscription is torn down and a fresh one opens for the new args (matching
-* `@lunora/react`/`@lunora/solid`). Pass `"skip"` (or a source resolving to
-* `"skip"`) to short-circuit: no network call, no socket. The subscription tears
-* down automatically when the owning component unmounts (or the effect scope
-* stops).
-*
-* Call inside `setup()` (or any active effect scope). For SSR seeding with no
-* loading flash, use `hydratePreloaded` instead.
-*/
+ * Subscribe to a server query and expose its latest value as a `ref`.
+ *
+ * The returned ref is `undefined` until the first server response lands, then
+ * updates on every delta the server pushes — the Vue-idiomatic equivalent of
+ * React's `useQuery`. `args` may be a plain value, a `ref`, or a getter: passing
+ * a reactive source makes the subscription reactive — when the args change the
+ * old subscription is torn down, the ref resets to `undefined`, and a fresh one
+ * opens for the new args (matching `@lunora/react`/`@lunora/solid`). Pass `"skip"` (or a source resolving to
+ * `"skip"`) to short-circuit: no network call, no socket. The subscription tears
+ * down automatically when the owning component unmounts (or the effect scope
+ * stops).
+ *
+ * Call inside `setup()` (or any active effect scope). For SSR seeding with no
+ * loading flash, use `hydratePreloaded` instead.
+ *
+ * Pass `onError` to surface a subscription-scoped error the server pushes (an RLS
+ * denial, a query that starts failing server-side). Without it such an error is
+ * dropped and the ref just freezes at its last good value.
+ */
 declare const useQuery: <F extends FunctionReference>(function_: F, args: MaybeRefOrGetter<ArgsOf<F> | "skip">, options?: UseQueryOptions) => Ref<ReturnOf<F> | undefined>;
 interface UseRateLimitOptions {
   /** Clock injection for tests. Defaults to `Date.now`. */
   now?: () => number;
   /**
-  * Re-render cadence in milliseconds while throttled, so `retryAfter` ticks
-  * down and `disabled` flips back automatically. Defaults to `1000`.
-  */
+   * Re-render cadence in milliseconds while throttled, so `retryAfter` ticks
+   * down and `disabled` flips back automatically. Defaults to `1000`.
+   */
   tickMs?: number;
 }
 interface UseRateLimitResult {
@@ -387,31 +1024,306 @@ interface UseRateLimitResult {
   retryAfter: ComputedRef<number>;
 }
 /**
-* 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` accepts a plain object, a `ref`, or a getter (`MaybeRefOrGetter`).
-* When you pass a ref/getter it is tracked reactively — changing the config
-* re-derives `status` (and the `ok` / `disabled` / `retryAfter` views) on the
-* fly. A plain object keeps working unchanged; pass a stable reference (module
-* constant) so the reactive derived values stay settled.
-*/
+ * 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` accepts a plain object, a `ref`, or a getter (`MaybeRefOrGetter`).
+ * When you pass a ref/getter it is tracked reactively — changing the config
+ * re-derives `status` (and the `ok` / `disabled` / `retryAfter` views) on the
+ * fly. A plain object keeps working unchanged; pass a stable reference (module
+ * constant) so the reactive derived values stay settled.
+ */
 declare const useRateLimit: (config: MaybeRefOrGetter<RateLimitConfig>, options?: UseRateLimitOptions) => UseRateLimitResult;
+/** The lifecycle of a stream the composable is observing. */
+type UseStreamStatus = "complete" | "error" | "idle" | "streaming";
+interface UseStreamResult<T> {
+  /** Force-cancel the stream and resolve the iterator. Safe to call multiple times. */
+  cancel: () => void;
+  /** Chunks the server has pushed so far, in arrival order. */
+  chunks: Ref<ReadonlyArray<T>>;
+  error: Ref<Error | undefined>;
+  status: Ref<UseStreamStatus>;
+}
+interface UseStreamOptions {
+  /**
+   * 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;
+}
+/**
+ * Subscribe to a streaming query. Returns the chunks pushed so far plus a
+ * lifecycle status and a cancel function, all as refs. Changing the resolved
+ * `args` resets the stream — the previous iterator is cancelled and a fresh one
+ * opens with empty `chunks`.
+ *
+ * `args` may be a plain value, `ref`, or getter; resolving it to `"skip"` keeps
+ * the composable mounted without opening a stream (mirrors `useSubscription`).
+ * Nothing opens during SSR either — the stream attaches after hydration.
+ * The Vue counterpart to React's `useStream`, re-expressed with refs.
+ */
+declare const useStream: <F extends FunctionReference<"stream">>(function_: F, args: MaybeRefOrGetter<"skip" | ArgsOf<F>>, options?: UseStreamOptions) => UseStreamResult<ReturnOf<F>>;
 interface UseSubscriptionResult<T> {
   data: Ref<T | undefined>;
   error: Ref<Error | undefined>;
 }
 /**
-* Subscribe to a reactive server push stream. Returns `{ data, error }` refs
-* that update whenever the server emits a new value. Passing `"skip"` as `args`
-* (or a ref/getter that resolves to `"skip"`) tears down the subscription
-* without unmounting.
-*
-* Unlike `useQuery`, which tracks the full reactive cache, `useSubscription`
-* owns a single lightweight subscription and is suitable for ephemeral,
-* high-frequency streams.
-*/
+ * Subscribe to a reactive server push stream. Returns `{ data, error }` refs
+ * that update whenever the server emits a new value. Passing `"skip"` as `args`
+ * (or a ref/getter that resolves to `"skip"`) tears down the subscription
+ * without unmounting.
+ *
+ * Unlike `useQuery`, which tracks the full reactive cache, `useSubscription`
+ * owns a single lightweight subscription and is suitable for ephemeral,
+ * high-frequency streams.
+ */
 declare const useSubscription: <F extends FunctionReference>(function_: F, args: MaybeRefOrGetter<ArgsOf<F> | "skip">, options?: UseQueryOptions) => UseSubscriptionResult<ReturnOf<F>>;
-export { AuthLoading, Authenticated, type FlagContext, type FlagValue, type HeartbeatReference, LUNORA_INJECTION_KEY, type ListPresentReference, type MutationHandle, type MutatorHook, type PageItemOf, type PaginatedArgs, Unauthenticated, type UseAuthResult, type UseInfiniteQueryOptions, type UseInfiniteQueryResult, type UsePaginatedQueryOptions, type UsePaginatedQueryResult, type UsePresenceOptions, type UsePresenceResult, type UseQueryOptions, type UseRateLimitOptions, type UseRateLimitResult, type UseSubscriptionResult, createLunora, hydratePreloaded, provideLunora, subscribeToQuery, useAuth, useConnectionStatus, useFlag, useFlags, useInfiniteQuery, useLunora, useMutation, useMutator, usePaginatedQuery, usePresence, useQuery, useRateLimit, useSubscription };
+/**
+ * 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 Vue 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 composable 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 UseVoiceAgentOptions {
+  /**
+   * 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. May be a plain value, `ref`, or getter (resolved when the call opens). */
+  threadKey: MaybeRefOrGetter<string>;
+  /** The generated `api.agents.<name>Voice` reference — identifies the voice DO endpoint. */
+  voice: VoiceReference;
+}
+interface UseVoiceAgentResult {
+  /** The current input RMS (0–1) — drive a mic level meter. */
+  audioLevel: Readonly<Ref<number>>;
+  /** `true` once the WS `ready` handshake completed. */
+  connected: Readonly<Ref<boolean>>;
+  /** Tear down the call: close the socket, stop the mic, release audio. Idempotent. */
+  endCall: () => void;
+  /** The last transport/pipeline error, or `undefined`. */
+  error: Readonly<Ref<Error | undefined>>;
+  /** The live assistant text for the in-flight turn (grows via deltas; finalized on done). */
+  interimTranscript: Readonly<Ref<string>>;
+  /** `true` while the mic is muted. */
+  isMuted: Readonly<Ref<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>;
+  /** The current call lifecycle. */
+  status: Readonly<Ref<VoiceStatus>>;
+  /** Mute/unmute the microphone. Returns the new muted state. */
+  toggleMute: () => boolean;
+  /** The last finalized user utterance (STT result). */
+  transcript: Readonly<Ref<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 Vue refs. Pass the generated `api.agents.<name>Voice`
+ * reference (never a string), matching `useAgentChat`'s reference-passing style.
+ * The Vue counterpart to React's `useVoiceAgent`, re-expressed with refs; the
+ * per-call connection lives in a closure variable (a composable runs once per
+ * component, so no `ref`-of-ref 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 composable is drivable outside a browser.
+ */
+declare const useVoiceAgent: (options: UseVoiceAgentOptions) => UseVoiceAgentResult;
+export { type ActionHandle, type AgentApprovalGrant, type AgentChatMessage, type AgentLiveEvent, type AgentProgressEvent, type AgentThreadRecord, type AgentThreadStatus, type AgentTokenDelta, type AgentToolEvent, AuthLoading, Authenticated, type FlagValue, type HeartbeatReference,
+/**
+ * `@lunora/vue` — the Vue adapter for Lunora.
+ *
+ * Thin, idiomatic glue over the framework-neutral `@lunora/client` (which owns
+ * the WebSocket transport, subscription registry, offline queue, and
+ * delta-merge — zero React, zero Vue). This package re-expresses that contract
+ * as Vue composables:
+ *
+ * - `createLunora` / `provideLunora` / `useLunora` — provide/inject the client.
+ * - `useQuery` — a live `ref` that opens a WS subscription and updates on deltas (reactive args re-subscribe).
+ * - `useMutation` — an optimistic mutation handle (refs + awaitable `mutate`).
+ * - `hydratePreloaded` — seed a `ref` synchronously from an SSR `Preloaded` token (no loading flash), then attach the live subscription.
+ *
+ * Server-side preload helpers live in the socket-free `@lunora/vue/server`
+ * entry (`createServerClient`, `preloadQuery`). Nuxt's single-worker
+ * composition (Lunora mounted inside Nitro) is `@lunora/nuxt`, not this
+ * package — see [Bring your framework](/docs/frameworks/bring-your-framework).
+ */
+LUNORA_INJECTION_KEY, type ListPresentReference, type MutationHandle, type MutatorHook, type PageItemOf, type PaginatedArgs, Unauthenticated, type UseAgentApi, type UseAgentChatApi, type UseAgentChatOptions, type UseAgentChatResult, type UseAgentOptions, type UseAgentResult, type UseAgentStateApi, type UseAgentStateOptions, type UseAgentStateResult, type UseAgentToolEventsApi, type UseAgentToolEventsOptions, type UseAgentToolEventsResult, type UseAuthResult, type UseInfiniteQueryOptions, type UseInfiniteQueryResult, type UseLiveTopicOptions, type UseLiveTopicResult, type UsePaginatedQueryOptions, type UsePaginatedQueryResult, type UsePresenceOptions, type UsePresenceResult, type UseQueryOptions, type UseRateLimitOptions, type UseRateLimitResult, type UseStreamOptions, type UseStreamResult, type UseStreamStatus, type UseSubscriptionResult, type UseVoiceAgentOptions, type UseVoiceAgentResult, type VoiceAudioFormat, type VoiceReference, type VoiceStatus,
+/**
+ * `@lunora/vue` — the Vue adapter for Lunora.
+ *
+ * Thin, idiomatic glue over the framework-neutral `@lunora/client` (which owns
+ * the WebSocket transport, subscription registry, offline queue, and
+ * delta-merge — zero React, zero Vue). This package re-expresses that contract
+ * as Vue composables:
+ *
+ * - `createLunora` / `provideLunora` / `useLunora` — provide/inject the client.
+ * - `useQuery` — a live `ref` that opens a WS subscription and updates on deltas (reactive args re-subscribe).
+ * - `useMutation` — an optimistic mutation handle (refs + awaitable `mutate`).
+ * - `hydratePreloaded` — seed a `ref` synchronously from an SSR `Preloaded` token (no loading flash), then attach the live subscription.
+ *
+ * Server-side preload helpers live in the socket-free `@lunora/vue/server`
+ * entry (`createServerClient`, `preloadQuery`). Nuxt's single-worker
+ * composition (Lunora mounted inside Nitro) is `@lunora/nuxt`, not this
+ * package — see [Bring your framework](/docs/frameworks/bring-your-framework).
+ */
+createLunora, hydratePreloaded,
+/**
+ * `@lunora/vue` — the Vue adapter for Lunora.
+ *
+ * Thin, idiomatic glue over the framework-neutral `@lunora/client` (which owns
+ * the WebSocket transport, subscription registry, offline queue, and
+ * delta-merge — zero React, zero Vue). This package re-expresses that contract
+ * as Vue composables:
+ *
+ * - `createLunora` / `provideLunora` / `useLunora` — provide/inject the client.
+ * - `useQuery` — a live `ref` that opens a WS subscription and updates on deltas (reactive args re-subscribe).
+ * - `useMutation` — an optimistic mutation handle (refs + awaitable `mutate`).
+ * - `hydratePreloaded` — seed a `ref` synchronously from an SSR `Preloaded` token (no loading flash), then attach the live subscription.
+ *
+ * Server-side preload helpers live in the socket-free `@lunora/vue/server`
+ * entry (`createServerClient`, `preloadQuery`). Nuxt's single-worker
+ * composition (Lunora mounted inside Nitro) is `@lunora/nuxt`, not this
+ * package — see [Bring your framework](/docs/frameworks/bring-your-framework).
+ */
+provideLunora, subscribeToQuery, useAction, useAgent, useAgentChat, useAgentState, useAgentToolEvents, useAuth, useConnectionStatus, useFlag, useFlags, useInfiniteQuery, useLiveTopic,
+/**
+ * `@lunora/vue` — the Vue adapter for Lunora.
+ *
+ * Thin, idiomatic glue over the framework-neutral `@lunora/client` (which owns
+ * the WebSocket transport, subscription registry, offline queue, and
+ * delta-merge — zero React, zero Vue). This package re-expresses that contract
+ * as Vue composables:
+ *
+ * - `createLunora` / `provideLunora` / `useLunora` — provide/inject the client.
+ * - `useQuery` — a live `ref` that opens a WS subscription and updates on deltas (reactive args re-subscribe).
+ * - `useMutation` — an optimistic mutation handle (refs + awaitable `mutate`).
+ * - `hydratePreloaded` — seed a `ref` synchronously from an SSR `Preloaded` token (no loading flash), then attach the live subscription.
+ *
+ * Server-side preload helpers live in the socket-free `@lunora/vue/server`
+ * entry (`createServerClient`, `preloadQuery`). Nuxt's single-worker
+ * composition (Lunora mounted inside Nitro) is `@lunora/nuxt`, not this
+ * package — see [Bring your framework](/docs/frameworks/bring-your-framework).
+ */
+useLunora, useMutation, useMutator, usePaginatedQuery, usePresence, useQuery, useRateLimit, useStream, useSubscription, useVoiceAgent };