@lunora/vue 1.0.0-alpha.35 → 1.0.0-alpha.37

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { Component, Ref, InjectionKey, App, DeepReadonly, MaybeRefOrGetter, ComputedRef, ShallowRef } from 'vue';
-import { Preloaded, LunoraClient, User, ConnectionStatus, FunctionReference, ReturnOf, ArgsOf, MutationCallOptions, MutatorHandle } from '@lunora/client';
+import { Component, Ref, InjectionKey, App, MaybeRefOrGetter, ComputedRef, DeepReadonly, ShallowRef } from 'vue';
+import { Preloaded, LunoraClient, FunctionReference, User, ConnectionStatus, 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 { PaginationStatus } from '@lunora/client/pagination';
 export type { PaginationResult, PaginationStatus } from '@lunora/client/pagination';
@@ -72,6 +72,409 @@ interface UseQueryOptions {
   /** Route to a specific shard when the target function is `.shardBy(...)`-partitioned. */
   shardKey?: string;
 }
+/**
+* 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"`. */
+  error?: 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.&lt;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">;
+  /**
+  * The app mutation that starts (or continues) a run — a thin wrapper over
+  * `ctx.agents.&lt;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>;
+  /** `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 placeholder mutation reference so `useMutation` is called unconditionally even
+* when the caller supplies no `cancel` mutation. Its `__lunoraRef` is never
+* dispatched — `cancel()` short-circuits before invoking it unless a real
+* reference was provided.
+*/
+/**
+* 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.&lt;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 lifecycle marker on a human-in-the-loop tool message. */
+  status?: "approved" | "awaiting_approval" | "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" | "reject";
+  instanceId: string;
+  note?: string;
+  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>;
+/**
+* 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: {
+    agentMessages: AgentMessagesReference$1;
+    agentResolveApproval: AgentApprovalReference;
+    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.&lt;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;
+  /**
+  * The app mutation that starts (or continues) a run — a thin wrapper over
+  * `ctx.agents.&lt;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 {
+  /** Approve a paused human-in-the-loop tool call (optionally with a note). */
+  approve: (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>;
+  /** 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>;
+  /** 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>;
+}
+/**
+* A first-class agent chat surface: live durable history + in-flight token
+* streaming + the send / approve / reject / 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) 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`) 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";
+};
+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;
   token: DeepReadonly<Ref<string | null>>;
@@ -399,6 +802,32 @@ interface UseRateLimitResult {
 * 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 {
+  /** 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`).
+* 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>;
@@ -414,4 +843,154 @@ interface UseSubscriptionResult<T> {
 * 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` while `status === "speaking"` — gates barge-in detection. */
+  isSpeaking: () => 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 default browser microphone: `getUserMedia` → a Web Audio `ScriptProcessor`
+* that tees 16 kHz PCM frames, tracks input RMS, auto-commits an utterance after
+* a silence gap, and flags a barge-in while the agent is speaking.
+*/
+/**
+* The `agents.&lt;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.&lt;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 `new WebSocket(url)`. */
+  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.&lt;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.&lt;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 AgentChatMessage, type AgentLiveEvent, type AgentProgressEvent, type AgentThreadRecord, type AgentThreadStatus, type AgentTokenDelta, type AgentToolEvent, AuthLoading, Authenticated, type FlagContext, type FlagValue, type HeartbeatReference, 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 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, createLunora, hydratePreloaded, provideLunora, subscribeToQuery, useAgent, useAgentChat, useAgentState, useAgentToolEvents, useAuth, useConnectionStatus, useFlag, useFlags, useInfiniteQuery, useLunora, useMutation, useMutator, usePaginatedQuery, usePresence, useQuery, useRateLimit, useStream, useSubscription, useVoiceAgent };