@lunora/angular 1.0.0-alpha.7 → 1.0.0-alpha.9

package/dist/index.d.mts

@@ -1,15 +1,504 @@
 import { DestroyRef, Signal, InjectionToken, EnvironmentProviders } from '@angular/core';
-import { LunoraClient, User, LunoraClientOptions, ConnectionStatus, SubscriptionError, Preloaded, FunctionReference, ArgsOf, ReturnOf, MutationCallOptions, MutatorHandle } from '@lunora/client';
+import { FunctionReference, LunoraClient, SubscriptionError, User, LunoraClientOptions, ConnectionStatus, Preloaded, ArgsOf, ReturnOf, MutationCallOptions, MutatorHandle } from '@lunora/client';
 export type { ArgsOf, ConnectionStatus, FunctionReference, LunoraClient, LunoraClientOptions, MutationCallOptions, Preloaded, ReturnOf, SubscriptionError, Unsubscribe } from '@lunora/client';
 import { PaginationStatus } from '@lunora/client/pagination';
 import { RateLimitStatus, RateLimitConfig } from '@lunora/ratelimit';
 export { SKIP } from '@lunora/client/query';
+/**
+* The lifecycle status stored on an agent thread. Client-safe mirror of
+* `@lunora/agent`'s `AgentThreadStatus` — re-declared here (rather than imported)
+* so this Angular entry never pulls in the server-only `@lunora/agent` module graph
+* (the adapter stays Angular + `@lunora/client` only). Keep in sync with
+* `packages/agent/src/types.ts`.
+* @experimental
+*/
+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`.
+* @experimental
+*/
+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;
+}
+/**
+* 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 Angular 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`.
+* @experimental
+*/
+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 the chat surface's
+* streaming text live and are never replayed; the persisted assistant message
+* stays the single source of truth.
+* @experimental
+*/
+interface AgentTokenDelta {
+  /** Discriminates the token arm of {@link AgentLiveEvent}; unset on the wire (token is the default). */
+  kind?: "token";
+  /** The incremental text chunk the model just produced. */
+  text: string;
+  /** The thread this delta belongs to. */
+  threadKey: string;
+  /** The zero-based index of the turn producing the delta. */
+  turn: number;
+}
+/**
+* A live tool-progress event streamed via `ctx.reportProgress(...)`. Client-safe
+* mirror of `@lunora/agent`'s `AgentProgressEvent`. Ephemeral and `toolCallId`-keyed;
+* surfaced by `agentToolEvents`, ignored by the chat surface's streaming text.
+* @experimental
+*/
+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).
+* @experimental
+*/
+type AgentLiveEvent = AgentProgressEvent | AgentTokenDelta;
+/**
+* The `agents.agentThread` reference the primitive 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.
+* @experimental
+*/
+interface AgentApi {
+  agents: {
+    agentThread: FunctionReference<"query", {
+      key: string;
+    }, Record<string, unknown> | undefined>;
+  };
+}
+/**
+* `AgentOptions` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+* @experimental
+*/
+interface AgentOptions {
+  /** The generated `api` — its `agents.agentThread` query drives live thread state. */
+  api: AgentApi;
+  /**
+  * Optional app mutation over the agent's cancel path
+  * (`ctx.agents.&lt;name>.cancel(id)`). Called with `{ instanceId, threadKey }`.
+  * When omitted (or no run is in flight) {@link AgentResult.cancel} is a no-op.
+  */
+  cancel?: FunctionReference<"mutation">;
+  /** Client to bind to. Defaults to the injected `LUNORA_CLIENT`. */
+  client?: LunoraClient;
+  /**
+  * `DestroyRef` whose `onDestroy` tears the live subscription down. Defaults to
+  * `inject(DestroyRef)` — the calling component/service.
+  */
+  destroyRef?: DestroyRef;
+  /**
+  * 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 AgentOptions.runArgs} and the per-call args.
+  */
+  run: FunctionReference<"mutation">;
+  /** Extra args merged into every `run` call (e.g. an `owner` or `title`). */
+  runArgs?: Record<string, unknown>;
+  /** The thread to observe and drive. */
+  threadKey: string;
+}
+/**
+* `AgentResult` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+* @experimental
+*/
+interface AgentResult {
+  /**
+  * 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: Signal<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: Signal<AgentThreadStatus | undefined>;
+  /** The live thread record (status, `instanceId`, …), or `undefined` before it exists. */
+  thread: Signal<AgentThreadRecord | undefined>;
+}
+/**
+* A thin agent handle: live thread `status` plus `run` / `cancel`, without the
+* chat message surface. Composes `subscription(api.agents.agentThread)` for live
+* state and drives the run/cancel writes straight on the client — the Angular
+* counterpart to React's `useAgent`, re-expressed with signals. For the full
+* conversation surface (durable history + streaming + approvals) use `agentChat`.
+*
+* `run` and `cancel` stay generic over the app-defined mutations that wrap
+* `ctx.agents.&lt;name>.run` / `.cancel`, so the primitive hard-codes no function
+* names beyond the `agents:*` surface.
+*
+* Call from an injection context (component/service field or constructor); pass an
+* explicit `client` / `destroyRef` to drive it outside one (e.g. in a test).
+* @experimental
+*/
+declare const agent: (options: AgentOptions) => AgentResult;
+/** 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 primitive consumes only the token arm.
+* @experimental
+*/
+type AgentTokenStreamReference = FunctionReference<"stream", {
+  key: string;
+}, AgentLiveEvent>;
+/**
+* The `agents.*` reference surface the chat primitive reads. A structural subset
+* of the generated `api.agents`, so the whole generated `api` object is
+* assignable.
+* @experimental
+*/
+interface AgentChatApi {
+  agents: {
+    agentMessages: AgentMessagesReference$1;
+    agentResolveApproval: AgentApprovalReference;
+    agentThread: AgentThreadReference;
+  };
+}
+/**
+* `AgentChatOptions` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+* @experimental
+*/
+interface AgentChatOptions {
+  /** The generated `api` — its `agents.*` surface provides history, thread state, and approval resolution. */
+  api: AgentChatApi;
+  /**
+  * Optional app mutation over the agent's cancel path
+  * (`ctx.agents.&lt;name>.cancel(id)`). Called with `{ instanceId, threadKey }`.
+  * When omitted (or no run is in flight) {@link AgentChatResult.cancel} is a
+  * no-op.
+  */
+  cancel?: FunctionReference<"mutation">;
+  /** Client to bind to. Defaults to the injected `LUNORA_CLIENT`. */
+  client?: LunoraClient;
+  /**
+  * `DestroyRef` whose `onDestroy` tears the subscriptions + stream down. Defaults
+  * to `inject(DestroyRef)` — the calling component/service.
+  */
+  destroyRef?: DestroyRef;
+  /** 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 AgentChatOptions.sendArgs} and the per-call args.
+  */
+  send: FunctionReference<"mutation">;
+  /** Extra args merged into every `send` call (e.g. an `owner` or `title`). */
+  sendArgs?: Record<string, unknown>;
+  /**
+  * Optional live token-delta stream — an app stream function that tees the
+  * agent's in-flight deltas. When omitted {@link AgentChatResult.streamingText}
+  * stays empty and the UI updates message-by-message from durable history.
+  */
+  stream?: AgentTokenStreamReference;
+  /** The thread to observe and continue. */
+  threadKey: string;
+}
+/**
+* `AgentChatResult` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+* @experimental
+*/
+interface AgentChatResult {
+  /** 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: Signal<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: Signal<AgentThreadStatus | undefined>;
+  /** The in-flight turn's streamed text — live-only, empty once the turn persists to `messages`. */
+  streamingText: Signal<string>;
+}
+/**
+* A first-class agent chat surface: live durable history + in-flight token
+* streaming + the send / approve / reject / cancel writes, keyed by `threadKey` —
+* the Angular counterpart to React's `useAgentChat`, re-expressed with signals.
+*
+* It composes the existing primitives rather than adding transport:
+* `subscription(api.agents.agentMessages)` for durable history,
+* `subscription(api.agents.agentThread)` for live status + the in-flight
+* `instanceId`, {@link stream} over an app token stream for in-flight deltas, and
+* the client's own `mutation` for the writes (`api.agents.agentResolveApproval` for
+* approvals; app-defined wrappers for `send`/`cancel`). Only the `agents:*` surface
+* is hard-coded — `send`/`cancel`/`stream` stay generic references.
+*
+* A `send` optimistically appends the user turn so it renders immediately; the
+* optimistic row clears once the durable history carries the acknowledged turn.
+* `streamingText` is live-only: it holds the current turn's streamed text and
+* empties as soon as that turn's assistant message lands in `messages` (the
+* persisted message is the source of truth), consistent with the loop's
+* replay-safe, live-only delta design.
+*
+* Call from an injection context (component/service field or constructor); pass an
+* explicit `client` / `destroyRef` to drive it outside one (e.g. in a test).
+* @experimental
+*/
+declare const agentChat: (options: AgentChatOptions) => AgentChatResult;
+/**
+* The `agents.agentState` reference the primitive subscribes to for the thread's
+* live synced state. A structural subset of the generated `api.agents` surface
+* (like `AgentApi` for `agentThread`), so the whole generated `api` object is
+* assignable. Client-safe: no `@lunora/agent` import — the per-agent state type is
+* mirrored by the primitive's generic `T`, since codegen pins the reference return
+* as an optional record (it never evaluates agent config).
+* @experimental
+*/
+interface AgentStateApi {
+  agents: {
+    agentState: FunctionReference<"query", {
+      key: string;
+    }, Record<string, unknown> | undefined>;
+  };
+}
+/**
+* `AgentStateOptions` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+* @experimental
+*/
+interface AgentStateOptions {
+  /** The generated `api` — its `agents.agentState` query drives live thread state. */
+  api: AgentStateApi;
+  /** Client to bind to. Defaults to the injected `LUNORA_CLIENT`. */
+  client?: LunoraClient;
+  /**
+  * `DestroyRef` whose `onDestroy` tears the subscription down. Defaults to
+  * `inject(DestroyRef)` — the calling component/service.
+  */
+  destroyRef?: DestroyRef;
+  /** The thread whose synced state to observe. */
+  threadKey: string;
+}
+/**
+* `AgentStateResult` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+* @experimental
+*/
+interface AgentStateResult<T> {
+  /** The subscription error, if the live channel reported one. */
+  error: Signal<SubscriptionError | undefined>;
+  /** The live synced state, or `undefined` before it is seeded/first pushed. */
+  state: Signal<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 `subscription(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 Angular counterpart to React's `useAgentState`,
+* re-expressed with signals.
+*
+* Generic over the app's state shape (`agentState&lt;SupportState>(...)`, itself a
+* record) — the reference is typed as an optional record because codegen cannot see
+* the per-agent state type; the generic casts to `T`. The `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.
+*
+* Call from an injection context (component/service field or constructor); pass an
+* explicit `client` / `destroyRef` to drive it outside one (e.g. in a test).
+* @experimental
+*/
+declare const agentState: <T extends Record<string, unknown> = Record<string, unknown>>(options: AgentStateOptions) => AgentStateResult<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 primitive consumes
+* only the progress arm (`kind === "progress"`).
+*/
+type AgentLiveStreamReference = FunctionReference<"stream", {
+  key: string;
+}, AgentLiveEvent>;
+/**
+* The `agents.*` reference surface the tool-events primitive reads. A structural
+* subset of the generated `api.agents`, so the whole generated `api` object is
+* assignable.
+* @experimental
+*/
+interface AgentToolEventsApi {
+  agents: {
+    agentMessages: AgentMessagesReference;
+  };
+}
+/**
+* `AgentToolEventsOptions` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+* @experimental
+*/
+interface AgentToolEventsOptions {
+  /** The generated `api` — its `agents.agentMessages` query provides the durable tool lifecycle. */
+  api: AgentToolEventsApi;
+  /** Client to bind to. Defaults to the injected `LUNORA_CLIENT`. */
+  client?: LunoraClient;
+  /**
+  * `DestroyRef` whose `onDestroy` tears the subscription + stream down. Defaults
+  * to `inject(DestroyRef)` — the calling component/service.
+  */
+  destroyRef?: DestroyRef;
+  /** History depth forwarded to `agents:agentMessages`. */
+  limit?: number;
+  /**
+  * Optional live event stream — the same app stream function `agentChat` uses.
+  * When supplied, ephemeral `ctx.reportProgress(...)` events for the thread are
+  * surfaced as `{ type: "progress" }` entries; when omitted only the durable
+  * lifecycle (call / result / awaiting-approval) is returned.
+  */
+  stream?: AgentLiveStreamReference;
+  /** The thread whose tool activity to observe. */
+  threadKey: string;
+}
+/**
+* A single tool-lifecycle event for a thread. The durable arms
+* (`call`/`result`/`awaiting-approval`) 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`.
+* @experimental
+*/
+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";
+};
+/**
+* `AgentToolEventsResult` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+* @experimental
+*/
+interface AgentToolEventsResult {
+  /**
+  * 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: Signal<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 Angular counterpart to React's
+* `useAgentToolEvents`, re-expressed as a `computed` signal.
+*
+* It composes the existing primitives rather than adding transport:
+* `subscription(api.agents.agentMessages)` for the durable lifecycle and
+* {@link stream} 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 `agentChat`; this primitive is the tool-observability slice.
+*
+* Call from an injection context (component/service field or constructor); pass an
+* explicit `client` / `destroyRef` to drive it outside one (e.g. in a test).
+* @experimental
+*/
+declare const agentToolEvents: (options: AgentToolEventsOptions) => AgentToolEventsResult;
+/**
+* `AuthOptions` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+* @experimental
+*/
 interface AuthOptions {
   /** Client to bind to. Defaults to the injected `LUNORA_CLIENT`. */
   client?: LunoraClient;
   /** `DestroyRef` whose `onDestroy` removes the listeners. Defaults to `inject(DestroyRef)`. */
   destroyRef?: DestroyRef;
 }
+/**
+* `AuthResult` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+* @experimental
+*/
 interface AuthResult {
   /** Set the auth token (sign-in / sign-out). */
   setToken: (token: string | null) => void;
@@ -32,6 +521,7 @@ interface AuthResult {
 * ```ts
 * const { token, user, setToken } = auth();
 * ```
+* @experimental
 */
 declare const auth: (options?: AuthOptions) => AuthResult;
 /**
@@ -44,6 +534,7 @@ declare const auth: (options?: AuthOptions) => AuthResult;
 * {@link provideLunora}: it builds one same-origin browser client (which opens
 * its WebSocket lazily on the first subscription). Call {@link provideLunora} to
 * point it at a remote URL or hand it a pre-built client.
+* @experimental
 */
 declare const LUNORA_CLIENT: InjectionToken<LunoraClient>;
 /**
@@ -51,6 +542,7 @@ declare const LUNORA_CLIENT: InjectionToken<LunoraClient>;
 * except `url` is optional — it defaults to the page origin in the browser (and to
 * `""` on the server; pass an explicit `url` for SSR data-loading — see
 * {@link sameOriginUrl}).
+* @experimental
 */
 type ProvideLunoraOptions = Omit<LunoraClientOptions, "url"> & {
   url?: string;
@@ -69,6 +561,7 @@ type ProvideLunoraOptions = Omit<LunoraClientOptions, "url"> & {
 * Pass {@link LunoraClientOptions} to configure a fresh client (URL defaults to
 * the page origin), or hand in an already-constructed {@link LunoraClient} to
 * share one instance (e.g. a client you also preload against during SSR).
+* @experimental
 */
 declare const provideLunora: (optionsOrClient?: LunoraClient | ProvideLunoraOptions) => EnvironmentProviders;
 /**
@@ -82,8 +575,13 @@ declare const provideLunora: (optionsOrClient?: LunoraClient | ProvideLunoraOpti
 * private readonly client = injectLunoraClient();
 * send = (text: string) => this.client.mutation(api.messages.send, { text });
 * ```
+* @experimental
 */
 declare const injectLunoraClient: () => LunoraClient;
+/**
+* `ConnectionStatusOptions` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+* @experimental
+*/
 interface ConnectionStatusOptions {
   /** Client to observe. Defaults to the injected `LUNORA_CLIENT`. */
   client?: LunoraClient;
@@ -98,12 +596,23 @@ interface ConnectionStatusOptions {
 *
 * The listener is removed when the owning `DestroyRef` fires. Call from an
 * injection context (component/service field or constructor).
+* @experimental
 */
 declare const connectionStatus: (options?: ConnectionStatusOptions) => Signal<ConnectionStatus>;
-/** The value kinds a flag resolves to — OpenFeature's boolean / number / string / structured (JSON) flags. */
+/**
+* The value kinds a flag resolves to — OpenFeature's boolean / number / string / structured (JSON) flags.
+* @experimental
+*/
 type FlagValue = boolean | number | string | Record<string, unknown> | unknown[] | null;
-/** Targeting context bag forwarded to the OpenFeature provider. */
+/**
+* Targeting context bag forwarded to the OpenFeature provider.
+* @experimental
+*/
 type FlagContext = Record<string, unknown>;
+/**
+* `FlagOptions` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+* @experimental
+*/
 interface FlagOptions {
   /** Client to bind to. Defaults to the injected `LUNORA_CLIENT`. */
   client?: LunoraClient;
@@ -131,8 +640,13 @@ interface FlagOptions {
 * ```ts
 * readonly darkMode = flag("dark-mode", false);
 * ```
+* @experimental
 */
 declare const flag: <T extends FlagValue>(key: string, defaultValue: T, options?: FlagOptions) => Signal<T>;
+/**
+* `FlagsOptions` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+* @experimental
+*/
 interface FlagsOptions {
   /** Client to bind to. Defaults to the injected `LUNORA_CLIENT`. */
   client?: LunoraClient;
@@ -155,14 +669,23 @@ interface FlagsOptions {
 * ```ts
 * readonly features = flags({ "dark-mode": false, "new-editor": false });
 * ```
+* @experimental
 */
 declare const flags: <T extends Record<string, FlagValue>>(flagDefaults: T, options?: FlagsOptions) => Signal<T>;
+/**
+* `HydratePreloadedOptions` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+* @experimental
+*/
 interface HydratePreloadedOptions {
   /** Client to bind to. Defaults to the injected `LUNORA_CLIENT`. */
   client?: LunoraClient;
   /** `DestroyRef` whose `onDestroy` tears the subscription down. Defaults to `inject(DestroyRef)`. */
   destroyRef?: DestroyRef;
 }
+/**
+* `HydratePreloadedResult` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+* @experimental
+*/
 interface HydratePreloadedResult<T> {
   /** The latest value pushed by the server. Seeded synchronously from the preloaded value. */
   data: Signal<T | undefined>;
@@ -186,8 +709,13 @@ interface HydratePreloadedResult<T> {
 * ```ts
 * readonly { data, error } = hydratePreloaded(preloadedMessages);
 * ```
+* @experimental
 */
 declare const hydratePreloaded: <T>(preloaded: Preloaded<T>, options?: HydratePreloadedOptions) => HydratePreloadedResult<T>;
+/**
+* `LiveQueryOptions` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+* @experimental
+*/
 interface LiveQueryOptions {
   /**
   * Client to bind to. Defaults to the injected `LUNORA_CLIENT`; pass one
@@ -233,8 +761,13 @@ interface LiveQueryOptions {
 * short-circuit — no network call, no socket; the signal stays `undefined`. To
 * call outside an injection context (e.g. lazily in `ngOnInit`), supply `client`
 * and `destroyRef` via {@link LiveQueryOptions}.
+* @experimental
 */
 declare const liveQuery: <F extends FunctionReference>(reference: F, args: ArgsOf<F> | "skip", options?: LiveQueryOptions) => Signal<ReturnOf<F> | undefined>;
+/**
+* `MutateOptions` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+* @experimental
+*/
 interface MutateOptions<F extends FunctionReference> extends MutationCallOptions<unknown, unknown, ArgsOf<F>> {
   /**
   * Client to run the mutation on. Defaults to the injected `LUNORA_CLIENT`.
@@ -261,8 +794,13 @@ interface MutateOptions<F extends FunctionReference> extends MutationCallOptions
 *
 * When called from within an injection context you may omit `client` and let it
 * resolve from the injector.
+* @experimental
 */
 declare const mutate: <F extends FunctionReference>(reference: F, args: ArgsOf<F>, options?: MutateOptions<F>) => Promise<ReturnOf<F>>;
+/**
+* `MutatorResult` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+* @experimental
+*/
 interface MutatorResult<TArgs> {
   /** The latest invocation's error, or `undefined`. */
   error: Signal<Error | undefined>;
@@ -291,6 +829,7 @@ interface MutatorResult<TArgs> {
 * private readonly collection = bindMutators(collections);
 * readonly mutator = mutator(this.collection.insert);
 * ```
+* @experimental
 */
 declare const mutator: <TArgs = Record<string, unknown>>(handle: MutatorHandle<TArgs>) => MutatorResult<TArgs>;
 /** The args a paginated query exposes minus the framework-supplied page cursor. */
@@ -301,6 +840,10 @@ type PageItemOf<F extends FunctionReference> = ReturnTypeOf<F> extends {
 } ? T : unknown;
 type ArgsOfRaw<F extends FunctionReference> = F extends FunctionReference<"query", infer A> ? A : never;
 type ReturnTypeOf<F extends FunctionReference> = F extends FunctionReference<"query", unknown, infer R> ? R : never;
+/**
+* Options for the paginated query — part of the experimental `@lunora/angular` API and may change without a major version bump.
+* @experimental
+*/
 interface PaginatedQueryOptions {
   /** Client to bind to. Defaults to the injected `LUNORA_CLIENT`. */
   client?: LunoraClient;
@@ -311,6 +854,10 @@ interface PaginatedQueryOptions {
   /** Route to a specific shard when the target function is `.shardBy(...)`-partitioned. */
   shardKey?: string;
 }
+/**
+* `PaginatedQueryResult` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+* @experimental
+*/
 interface PaginatedQueryResult<T> {
   /** `true` while the first page or a `loadMore` page is in flight. */
   isLoading: Signal<boolean>;
@@ -321,6 +868,10 @@ interface PaginatedQueryResult<T> {
   /** The pagination status. */
   status: Signal<PaginationStatus>;
 }
+/**
+* `InfiniteQueryResult` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+* @experimental
+*/
 interface InfiniteQueryResult<T> {
   /** Request the next page. A no-op unless `status === "CanLoadMore"`. */
   fetchNextPage: (numberItems?: number) => void;
@@ -350,6 +901,7 @@ interface InfiniteQueryResult<T> {
 * ```ts
 * readonly messages = paginatedQuery(api.messages.list, {}, { initialNumItems: 20 });
 * ```
+* @experimental
 */
 declare const paginatedQuery: <F extends FunctionReference>(reference: F, args: PaginatedArgs<F> | "skip", options: PaginatedQueryOptions) => PaginatedQueryResult<PageItemOf<F>>;
 /**
@@ -363,16 +915,29 @@ declare const paginatedQuery: <F extends FunctionReference>(reference: F, args:
 * ```ts
 * readonly feed = infiniteQuery(api.messages.list, {}, { initialNumItems: 20 });
 * ```
+* @experimental
 */
 declare const infiniteQuery: <F extends FunctionReference>(reference: F, args: PaginatedArgs<F> | "skip", options: PaginatedQueryOptions) => InfiniteQueryResult<PageItemOf<F>>;
+/**
+* `HeartbeatReference` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+* @experimental
+*/
 type HeartbeatReference = FunctionReference<"mutation", {
   data?: Record<string, unknown>;
   roomId: string;
   sessionId: string;
 }>;
+/**
+* `ListPresentReference` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+* @experimental
+*/
 type ListPresentReference = FunctionReference<"query", {
   roomId: string;
 }>;
+/**
+* `PresenceOptions` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+* @experimental
+*/
 interface PresenceOptions<H extends HeartbeatReference, L extends ListPresentReference> {
   /** Client to bind to. Defaults to the injected `LUNORA_CLIENT`. */
   client?: LunoraClient;
@@ -394,6 +959,10 @@ interface PresenceOptions<H extends HeartbeatReference, L extends ListPresentRef
   /** Forwarded to the heartbeat mutation / listPresent subscription when sharding by room. */
   shardKey?: string;
 }
+/**
+* `PresenceResult` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+* @experimental
+*/
 interface PresenceResult<L extends ListPresentReference> {
   /** The present members for the room. `undefined` until the first push. */
   present: Signal<ReturnOf<L> | undefined>;
@@ -416,8 +985,13 @@ interface PresenceResult<L extends ListPresentReference> {
 *     listPresent: api.presence.listPresent,
 * });
 * ```
+* @experimental
 */
 declare const presence: <H extends HeartbeatReference, L extends ListPresentReference>(roomId: string, options: PresenceOptions<H, L>) => PresenceResult<L>;
+/**
+* `RateLimitOptions` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+* @experimental
+*/
 interface RateLimitOptions {
   /**
   * `DestroyRef` whose `onDestroy` clears the interval. Defaults to
@@ -432,6 +1006,10 @@ interface RateLimitOptions {
   */
   tickMs?: number;
 }
+/**
+* `RateLimitResult` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+* @experimental
+*/
 interface RateLimitResult {
   /** Would consuming `count` (default 1) succeed right now? Does not consume. */
   check: (count?: number) => boolean;
@@ -458,8 +1036,67 @@ interface RateLimitResult {
 * ```ts
 * readonly sendLimit = rateLimit({ kind: "token bucket", period: 1000, rate: 10 });
 * ```
+* @experimental
 */
 declare const rateLimit: (config: RateLimitConfig, options?: RateLimitOptions) => RateLimitResult;
+/**
+* The lifecycle of a stream the primitive is observing.
+* @experimental
+*/
+type StreamStatus = "complete" | "error" | "idle" | "streaming";
+/**
+* `StreamOptions` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+* @experimental
+*/
+interface StreamOptions {
+  /** Client to bind to. Defaults to the injected `LUNORA_CLIENT`. */
+  client?: LunoraClient;
+  /**
+  * `DestroyRef` whose `onDestroy` cancels the stream. Defaults to
+  * `inject(DestroyRef)` — the calling component/service.
+  */
+  destroyRef?: DestroyRef;
+  /** Forwarded to `client.stream()` — caps the in-flight chunk buffer. */
+  maxBuffer?: number;
+  /** Route to a specific shard when the target function is `.shardBy(...)`-partitioned. */
+  shardKey?: string;
+}
+/**
+* `StreamResult` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+* @experimental
+*/
+interface StreamResult<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: Signal<ReadonlyArray<T>>;
+  /** The stream error, or `undefined`. */
+  error: Signal<Error | undefined>;
+  /** The stream lifecycle. */
+  status: Signal<StreamStatus>;
+}
+/**
+* Subscribe to a streaming query. Returns the chunks pushed so far plus a
+* lifecycle status and a `cancel` function, all as signals.
+*
+* Unlike `subscription`, which tracks the latest value, `stream` accumulates every
+* chunk the server pushes — use it for token-by-token deltas and other append-only
+* feeds. Pass `"skip"` as `args` to keep the primitive mounted without opening a
+* stream (mirrors `subscription`); the stream tears down when the owning
+* `DestroyRef` fires. The Angular counterpart to React's `useStream`, re-expressed
+* with signals.
+*
+* Call from an injection context (component/service field or constructor):
+* ```ts
+* readonly tokens = stream(api.chat.liveEvents, { key: "thread-1" });
+* ```
+* @experimental
+*/
+declare const stream: <F extends FunctionReference<"stream">>(reference: F, args: ArgsOf<F> | "skip", options?: StreamOptions) => StreamResult<ReturnOf<F>>;
+/**
+* `SubscriptionOptions` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+* @experimental
+*/
 interface SubscriptionOptions {
   /** Client to bind to. Defaults to the injected `LUNORA_CLIENT`. */
   client?: LunoraClient;
@@ -476,6 +1113,10 @@ interface SubscriptionOptions {
   /** Route to a specific shard when the target function is `.shardBy(...)`-partitioned. */
   shardKey?: string;
 }
+/**
+* `SubscriptionResult` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+* @experimental
+*/
 interface SubscriptionResult<T> {
   /** The latest value pushed by the server. `undefined` before the first frame. */
   data: Signal<T | undefined>;
@@ -497,6 +1138,181 @@ interface SubscriptionResult<T> {
 * ```ts
 * readonly stream = subscription(api.events.stream, { roomId: "general" });
 * ```
+* @experimental
 */
 declare const subscription: <F extends FunctionReference>(reference: F, args: ArgsOf<F> | "skip", options?: SubscriptionOptions) => SubscriptionResult<ReturnOf<F>>;
-export { type AuthOptions, type AuthResult, type ConnectionStatusOptions, type FlagContext, type FlagOptions, type FlagValue, type FlagsOptions, type HeartbeatReference, type HydratePreloadedOptions, type HydratePreloadedResult, type InfiniteQueryResult, LUNORA_CLIENT, type ListPresentReference, type LiveQueryOptions, type MutateOptions, type MutatorResult, type PaginatedQueryOptions, type PaginatedQueryResult, type PresenceOptions, type PresenceResult, type ProvideLunoraOptions, type RateLimitOptions, type RateLimitResult, type SubscriptionOptions, type SubscriptionResult, auth, connectionStatus, flag, flags, hydratePreloaded, infiniteQuery, injectLunoraClient, liveQuery, mutate, mutator, paginatedQuery, presence, provideLunora, rateLimit, subscription };
+/**
+* Browser Web Audio subsystems for `voiceAgent` — the default microphone capture
+* and speaker playback implementations injected into the primitive 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
+* primitive's transport + signal-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 Angular package never pulls in the server-only `@lunora/agent`
+* module graph.
+* @experimental
+*/
+type VoiceAudioFormat = "mp3" | "wav";
+/** Captures microphone audio and reports level / turn boundaries back to the primitive. */
+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.
+* @experimental
+*/
+type VoiceReference = FunctionReference<"stream", {
+  threadKey: string;
+}, Record<string, unknown>>;
+/**
+* The lifecycle of a voice call, mirrored to the UI.
+* @experimental
+*/
+type VoiceStatus = "idle" | "listening" | "speaking" | "thinking";
+/** A minimal structural subset of the DOM `WebSocket` the primitive 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;
+/**
+* `VoiceAgentOptions` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+* @experimental
+*/
+interface VoiceAgentOptions {
+  /** Client to bind to. Defaults to the injected `LUNORA_CLIENT`. */
+  client?: LunoraClient;
+  /**
+  * 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;
+  /**
+  * `DestroyRef` whose `onDestroy` tears the call down. Defaults to
+  * `inject(DestroyRef)` — the calling component/service.
+  */
+  destroyRef?: DestroyRef;
+  /** 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. Resolved when the call opens. */
+  threadKey: string;
+  /** The generated `api.agents.&lt;name>Voice` reference — identifies the voice DO endpoint. */
+  voice: VoiceReference;
+}
+/**
+* `VoiceAgentResult` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+* @experimental
+*/
+interface VoiceAgentResult {
+  /** The current input RMS (0–1) — drive a mic level meter. */
+  audioLevel: Signal<number>;
+  /** `true` once the WS `ready` handshake completed. */
+  connected: Signal<boolean>;
+  /** Tear down the call: close the socket, stop the mic, release audio. Idempotent. */
+  endCall: () => void;
+  /** The last transport/pipeline error, or `undefined`. */
+  error: Signal<Error | undefined>;
+  /** The live assistant text for the in-flight turn (grows via deltas; finalized on done). */
+  interimTranscript: Signal<string>;
+  /** `true` while the mic is muted. */
+  isMuted: Signal<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: Signal<VoiceStatus>;
+  /** Mute/unmute the microphone. Returns the new muted state. */
+  toggleMute: () => boolean;
+  /** The last finalized user utterance (STT result). */
+  transcript: Signal<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 Angular signals. Pass the generated `api.agents.&lt;name>Voice`
+* reference (never a string), matching `agentChat`'s reference-passing style. The
+* Angular counterpart to React's `useVoiceAgent`, re-expressed with signals; the
+* per-call connection lives in a closure variable (the primitive runs once per
+* component, so no signal-of-connection 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 primitive is drivable outside a browser.
+*
+* Call from an injection context (component/service field or constructor); pass an
+* explicit `client` / `destroyRef` to drive it outside one (e.g. in a test).
+* @experimental
+*/
+declare const voiceAgent: (options: VoiceAgentOptions) => VoiceAgentResult;
+export { type AgentApi, type AgentChatApi, type AgentChatMessage, type AgentChatOptions, type AgentChatResult, type AgentLiveEvent, type AgentOptions, type AgentProgressEvent, type AgentResult, type AgentStateApi, type AgentStateOptions, type AgentStateResult, type AgentThreadRecord, type AgentThreadStatus, type AgentTokenDelta, type AgentTokenStreamReference, type AgentToolEvent, type AgentToolEventsApi, type AgentToolEventsOptions, type AgentToolEventsResult, type AuthOptions, type AuthResult, type ConnectionStatusOptions, type FlagContext, type FlagOptions, type FlagValue, type FlagsOptions, type HeartbeatReference, type HydratePreloadedOptions, type HydratePreloadedResult, type InfiniteQueryResult, LUNORA_CLIENT, type ListPresentReference, type LiveQueryOptions, type MutateOptions, type MutatorResult, type PaginatedQueryOptions, type PaginatedQueryResult, type PresenceOptions, type PresenceResult, type ProvideLunoraOptions, type RateLimitOptions, type RateLimitResult, type StreamOptions, type StreamResult, type StreamStatus, type SubscriptionOptions, type SubscriptionResult, type VoiceAgentOptions, type VoiceAgentResult, type VoiceAudioFormat, type VoiceReference, type VoiceStatus, agent, agentChat, agentState, agentToolEvents, auth, connectionStatus, flag, flags, hydratePreloaded, infiniteQuery, injectLunoraClient, liveQuery, mutate, mutator, paginatedQuery, presence, provideLunora, rateLimit, stream, subscription, voiceAgent };