@lunora/angular 1.0.0-alpha.21 → 1.0.0-alpha.211

package/README.md

@@ -57,6 +57,31 @@ export class MessagesComponent {
 
 Pass `"skip"` as the args to short-circuit (no network call, no socket).
 
+Pass a function/`Signal` instead of a plain object to make the args reactive —
+each change tears the old subscription down, resets the signal to `undefined`,
+and opens a fresh one for the new args:
+
+```ts
+export class MessagesComponent {
+    private readonly channelId = input.required<string>();
+
+    readonly messages = liveQuery(api.messages.list, () => ({ channelId: this.channelId() }));
+}
+```
+
+`subscription` and `paginatedQuery`/`infiniteQuery` accept the same reactive
+args form. Calling from outside an injection context (e.g. `ngOnInit`) needs an
+explicit `injector` alongside `client`/`destroyRef` for the reactive form —
+`effect()` can't resolve one on its own there:
+
+```ts
+liveQuery(api.messages.list, () => ({ channelId: this.channelId() }), {
+    client: this.client,
+    destroyRef: this.destroyRef,
+    injector: this.injector,
+});
+```
+
 ## Mutations
 
 ```ts
@@ -85,4 +110,21 @@ import { connectionStatus } from "@lunora/angular";
 readonly status = connectionStatus(); // Signal<"idle" | "connecting" | "connected" | "offline">
 ```
 
+## Agents
+
+```ts
+import { agentToolEvents, voiceAgent } from "@lunora/angular";
+
+// One thread's tool lifecycle: call / result / awaiting-approval / progress.
+readonly events = agentToolEvents({ api, threadKey: "t1", stream: api.chat.liveEvents }).events;
+
+// A full-duplex voice call against api.agents.<name>Voice.
+readonly call = voiceAgent({ threadKey: "t1", voice: api.agents.supportVoice });
+```
+
+`voiceAgent` opens nothing until `call.startCall()` — that call is what requests
+the microphone, so it must run from a user gesture. `call.endCall()` releases the
+socket, the mic tracks and the Web Audio graph, and the owning `DestroyRef` runs
+it on destroy.
+
 Part of the [Lunora](https://github.com/anolilab/lunora) framework.

package/dist/index.d.mts

@@ -1,6 +1,7 @@
-import { DestroyRef, Signal, InjectionToken, EnvironmentProviders } from '@angular/core';
-import { FunctionReference, LunoraClient, SubscriptionError, User, LunoraClientOptions, ConnectionStatus, Preloaded, ArgsOf, ReturnOf, MutationCallOptions, MutatorHandle } from '@lunora/client';
+import { DestroyRef, Signal, InjectionToken, EnvironmentProviders, Injector } from '@angular/core';
+import { FunctionReference, LunoraClient, SubscriptionErrorCallback, SubscriptionError, User, LunoraClientOptions, ConnectionStatus, Preloaded, ArgsOf, ReturnOf, MutationCallOptions, MutatorHandle, ActionCallOptions } from '@lunora/client';
 export type { ArgsOf, ConnectionStatus, FunctionReference, LunoraClient, LunoraClientOptions, MutationCallOptions, Preloaded, ReturnOf, SubscriptionError, Unsubscribe } from '@lunora/client';
+import { AuthStatus } from '@lunora/client/auth';
 import { PaginationStatus } from '@lunora/client/pagination';
 import { RateLimitStatus, RateLimitConfig } from '@lunora/ratelimit';
 export { SKIP } from '@lunora/client/query';
@@ -22,8 +23,12 @@ type AgentThreadStatus = "awaiting_input" | "cancelled" | "error" | "idle" | "ru
  */
 interface AgentThreadRecord {
   createdAt?: number;
-  /** The failure message when `status === "error"`. */
-  error?: string;
+  /**
+   * 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;
@@ -125,7 +130,7 @@ interface AgentOptions {
   api: AgentApi;
   /**
    * Optional app mutation over the agent's cancel path
-   * (`ctx.agents.<name>.cancel(id)`). Called with `{ instanceId, threadKey }`.
+   * (`ctx.agents.<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">;
@@ -136,9 +141,15 @@ interface AgentOptions {
    * `inject(DestroyRef)` — the calling component/service.
    */
   destroyRef?: DestroyRef;
+  /**
+   * 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.&lt;name>.run(...)`. Called with `{ threadKey, input }` merged with
+   * `ctx.agents.<name>.run(...)`. Called with `{ threadKey, input }` merged with
    * {@link AgentOptions.runArgs} and the per-call args.
    */
   run: FunctionReference<"mutation">;
@@ -157,6 +168,8 @@ interface AgentResult {
    * 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: Signal<SubscriptionError | undefined>;
   /** `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`. */
@@ -174,7 +187,7 @@ interface AgentResult {
  * 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
+ * `ctx.agents.<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
@@ -232,7 +245,7 @@ interface AgentChatOptions {
   api: AgentChatApi;
   /**
    * Optional app mutation over the agent's cancel path
-   * (`ctx.agents.&lt;name>.cancel(id)`). Called with `{ instanceId, threadKey }`.
+   * (`ctx.agents.<name>.cancel(id)`). Called with `{ instanceId, threadKey }`.
    * When omitted (or no run is in flight) {@link AgentChatResult.cancel} is a
    * no-op.
    */
@@ -246,9 +259,15 @@ interface AgentChatOptions {
   destroyRef?: DestroyRef;
   /** History depth forwarded to `agents:agentMessages`. */
   limit?: number;
+  /**
+   * Called when the live history or thread 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.&lt;name>.run(...)`. Called with `{ threadKey, input }` merged with
+   * `ctx.agents.<name>.run(...)`. Called with `{ threadKey, input }` merged with
    * {@link AgentChatOptions.sendArgs} and the per-call args.
    */
   send: FunctionReference<"mutation">;
@@ -275,6 +294,8 @@ interface AgentChatResult {
    * no-op when no `cancel` mutation was supplied or no run is in flight.
    */
   cancel: () => Promise<void>;
+  /** The history or thread subscription's last error, or `undefined`. */
+  error: Signal<SubscriptionError | undefined>;
   /** 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). */
@@ -363,7 +384,7 @@ interface AgentStateResult<T> {
  * 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
+ * Generic over the app's state shape (`agentState<SupportState>(...)`, itself a
  * record) — the reference is typed as an optional record because codegen cannot see
  * the per-agent state type; the generic casts to `T`. The `extends` bound (not a
  * bare unbounded type parameter) is required: this `.ts` file is parsed JSX-aware by
@@ -502,6 +523,12 @@ interface AuthOptions {
 interface AuthResult {
   /** Set the auth token (sign-in / sign-out). */
   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: Signal<AuthStatus>;
   /** The current auth token, or `null`. */
   token: Signal<string | null>;
   /** The resolved user from `store.getUser()`, or `null`. */
@@ -529,18 +556,20 @@ declare const auth: (options?: AuthOptions) => AuthResult;
  * @experimental
  */
 interface AuthGateResult {
-  /** `true` once a token is set and the user has resolved. */
+  /** `true` once a credential is held and nothing has contradicted it. */
   isAuthenticated: Signal<boolean>;
-  /** `true` while a token is set but the user hasn't resolved yet. */
+  /** `true` while a credential's first identity resolve is in flight. */
   isLoading: Signal<boolean>;
 }
 /**
  * Derived auth-gate signals for template gating (Angular's `\@if` control
  * flow), built on {@link auth}. Angular has no JSX-style `Authenticated` slot
  * component the way React/Vue/Solid do, so this exposes the same three-state
- * logic as two booleans instead: a token with no resolved user yet is
- * `isLoading`; a token with a resolved user is `isAuthenticated`; no token is
- * neither (the signed-out state a template checks for with a plain `\@else`).
+ * logic as two booleans instead, mapped from the shared `AuthStatus` contract in
+ * `@lunora/client/auth`: a credential whose first identity resolve is in flight
+ * is `isLoading`; a credential nothing has contradicted — including one whose
+ * identity endpoint is unreachable — is `isAuthenticated`; no session is neither
+ * (the signed-out state a template checks for with a plain `\@else`).
  *
  * Call from an injection context (component/service field or constructor):
  * ```ts
@@ -625,16 +654,15 @@ interface ConnectionStatusOptions {
  * @experimental
  */
 declare const connectionStatus: (options?: ConnectionStatusOptions) => Signal<ConnectionStatus>;
+/** The value kinds a flag resolves to — OpenFeature's boolean / number / string / structured (JSON) flags. */
+type FlagValue$1 = boolean | number | string | {
+  [key: string]: unknown;
+} | unknown[] | null;
 /**
  * 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.
- * @experimental
- */
-type FlagContext = Record<string, unknown>;
+type FlagValue = FlagValue$1;
 /**
  * `FlagOptions` is part of the experimental `@lunora/angular` API and may change without a major version bump.
  * @experimental
@@ -642,11 +670,6 @@ type FlagContext = Record<string, unknown>;
 interface FlagOptions {
   /** Client to bind to. Defaults to the injected `LUNORA_CLIENT`. */
   client?: LunoraClient;
-  /**
-   * Per-call targeting context merged on top of the app's default `identify`
-   * targeting key.
-   */
-  context?: FlagContext;
   /** `DestroyRef` whose `onDestroy` tears down the subscription. Defaults to `inject(DestroyRef)`. */
   destroyRef?: DestroyRef;
 }
@@ -658,9 +681,16 @@ interface FlagOptions {
  * The flag's kind is inferred from `defaultValue`'s runtime type, so
  * `flag("dark", false)` reads a boolean and `flag("hero", "control")` a string.
  *
+ * The reactive channel is public, so the server evaluates every flag under the
+ * socket's own verified identity — the targeting key your `defineFlags({
+ * identify })` derives — and accepts no client-supplied targeting context. For
+ * evaluation under a context you compute, call `ctx.flags.*` inside a query,
+ * mutation, or action and return the resolved value.
+ *
  * 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`).
+ * default (the same fail-open contract as server-side `ctx.flags`). No
+ * subscription opens during SSR; the signal stays at `defaultValue`.
  *
  * Call from an injection context:
  * ```ts
@@ -676,11 +706,6 @@ declare const flag: <T extends FlagValue>(key: string, defaultValue: T, options?
 interface FlagsOptions {
   /** Client to bind to. Defaults to the injected `LUNORA_CLIENT`. */
   client?: LunoraClient;
-  /**
-   * Targeting context shared by every flag in the set, merged on top of the
-   * app's default `identify` targeting key.
-   */
-  context?: FlagContext;
   /** `DestroyRef` whose `onDestroy` tears down the subscriptions. Defaults to `inject(DestroyRef)`. */
   destroyRef?: DestroyRef;
 }
@@ -689,7 +714,8 @@ interface FlagsOptions {
  *
  * Pass a record of `key → defaultValue`; each flag's kind is inferred from its
  * default, and the returned signal holds the same-shaped record with resolved
- * values (the defaults until each evaluation lands).
+ * values (the defaults until each evaluation lands). Like {@link flag} it
+ * evaluates under the socket's server-verified identity only.
  *
  * Call from an injection context:
  * ```ts
@@ -713,7 +739,7 @@ interface HydratePreloadedOptions {
  * @experimental
  */
 interface HydratePreloadedResult<T> {
-  /** The latest value pushed by the server. Seeded synchronously from the preloaded value. */
+  /** The latest value pushed by the server. Seeded synchronously from the preloaded value until an identity is retired. */
   data: Signal<T | undefined>;
   /** The latest subscription error, or `undefined`. */
   error: Signal<SubscriptionError | undefined>;
@@ -731,6 +757,12 @@ interface HydratePreloadedResult<T> {
  *
  * The subscription tears down when the owning `DestroyRef` fires.
  *
+ * 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 (created
+ * then or later) stops using it and `data` holds `undefined` until the live value
+ * arrives — matching `@lunora/react`'s `usePreloadedQuery`.
+ *
  * Call from an injection context:
  * ```ts
  * readonly { data, error } = hydratePreloaded(preloadedMessages);
@@ -754,6 +786,16 @@ interface LiveQueryOptions {
    * component is destroyed. Pass one explicitly to control the lifetime yourself.
    */
   destroyRef?: DestroyRef;
+  /**
+   * `Injector` to create the reactive-args `effect()` from. Only needed when
+   * `args` is a function/`Signal` AND `liveQuery` is called outside an injection
+   * context (an explicit `destroyRef` is also being passed — e.g. from
+   * `ngOnInit`, or from a test with no `TestBed`) — `effect()` cannot resolve an
+   * injector on its own there. Defaults to the ambient injection context, the
+   * same source `inject(DestroyRef)` already relies on. Unused for the static
+   * `args` form, which never creates an `effect()`.
+   */
+  injector?: Injector;
   /**
    * Called when the subscription errors after the initial attach — the async
    * error channel `createQuerySubscription` only wires when a sink is present.
@@ -787,9 +829,17 @@ 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}.
+ *
+ * `args` also accepts a function/`Signal` — `() => ({ channelId: channelId() })`
+ * — to make the subscription reactive: an args change tears the old
+ * subscription down, resets the signal to `undefined`, and opens a fresh one
+ * for the new args, mirroring
+ * `@lunora/solid`'s `createQuery`/`@lunora/vue`'s `useQuery`. A static (plain
+ * object) `args` resolves once and never re-runs — no `effect()` is created for
+ * it, so it carries none of the reactive form's DI requirement.
  * @experimental
  */
-declare const liveQuery: <F extends FunctionReference>(reference: F, args: ArgsOf<F> | "skip", options?: LiveQueryOptions) => Signal<ReturnOf<F> | undefined>;
+declare const liveQuery: <F extends FunctionReference>(reference: F, args: ArgsOf<F> | "skip" | (() => 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
@@ -877,6 +927,15 @@ interface PaginatedQueryOptions {
   destroyRef?: DestroyRef;
   /** Page size for the first page (and the default for `loadMore`). */
   initialNumItems: number;
+  /**
+   * `Injector` to create the reactive-args `effect()` from. Only needed when
+   * `args` is a function/`Signal` AND the call is outside an injection context
+   * (an explicit `destroyRef` is also being passed). Defaults to the ambient
+   * injection context. Unused for the static `args` form.
+   */
+  injector?: Injector;
+  /** Called when a page subscription reports an error (also surfaced on the `error` signal). */
+  onError?: SubscriptionErrorCallback;
   /** Route to a specific shard when the target function is `.shardBy(...)`-partitioned. */
   shardKey?: string;
 }
@@ -885,6 +944,13 @@ interface PaginatedQueryOptions {
  * @experimental
  */
 interface PaginatedQueryResult<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: Signal<SubscriptionError | undefined>;
   /** `true` while the first page or a `loadMore` page is in flight. */
   isLoading: Signal<boolean>;
   /** Request the next page. A no-op unless `status === "CanLoadMore"`. */
@@ -899,6 +965,8 @@ interface PaginatedQueryResult<T> {
  * @experimental
  */
 interface InfiniteQueryResult<T> {
+  /** The last page subscription error, or `undefined` — see `PaginatedQueryResult.error`. */
+  error: Signal<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. */
@@ -927,9 +995,13 @@ interface InfiniteQueryResult<T> {
  * ```ts
  * readonly messages = paginatedQuery(api.messages.list, {}, { initialNumItems: 20 });
  * ```
+ *
+ * `args` also accepts a function/`Signal` to make the query reactive — an args
+ * change disposes the current pagination engine and builds a fresh one for the
+ * new args. A static (plain object) `args` resolves once and never re-runs.
  * @experimental
  */
-declare const paginatedQuery: <F extends FunctionReference>(reference: F, args: PaginatedArgs<F> | "skip", options: PaginatedQueryOptions) => PaginatedQueryResult<PageItemOf<F>>;
+declare const paginatedQuery: <F extends FunctionReference>(reference: F, args: PaginatedArgs<F> | "skip" | (() => PaginatedArgs<F> | "skip"), options: PaginatedQueryOptions) => PaginatedQueryResult<PageItemOf<F>>;
 /**
  * Subscribe to a reactively-paginated query and expose its pages discretely.
  *
@@ -941,9 +1013,12 @@ declare const paginatedQuery: <F extends FunctionReference>(reference: F, args:
  * ```ts
  * readonly feed = infiniteQuery(api.messages.list, {}, { initialNumItems: 20 });
  * ```
+ *
+ * `args` also accepts a function/`Signal` to make the query reactive — see
+ * `paginatedQuery`'s equivalent note.
  * @experimental
  */
-declare const infiniteQuery: <F extends FunctionReference>(reference: F, args: PaginatedArgs<F> | "skip", options: PaginatedQueryOptions) => InfiniteQueryResult<PageItemOf<F>>;
+declare const infiniteQuery: <F extends FunctionReference>(reference: F, args: PaginatedArgs<F> | "skip" | (() => 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
@@ -977,6 +1052,12 @@ interface PresenceOptions<H extends HeartbeatReference, L extends ListPresentRef
   intervalMs?: number;
   /** The `api.*` reference for the presence listPresent query. */
   listPresent: L;
+  /**
+   * 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-call id.
    * Pass a user/connection id to control deduping across tabs.
@@ -990,6 +1071,8 @@ interface PresenceOptions<H extends HeartbeatReference, L extends ListPresentRef
  * @experimental
  */
 interface PresenceResult<L extends ListPresentReference> {
+  /** The `listPresent` subscription's last error, or `undefined`. */
+  error: Signal<SubscriptionError | undefined>;
   /** The present members for the room. `undefined` until the first push. */
   present: Signal<ReturnOf<L> | undefined>;
   /** This mount's session id (generated when not supplied). */
@@ -1065,6 +1148,43 @@ interface RateLimitResult {
  * @experimental
  */
 declare const rateLimit: (config: RateLimitConfig, options?: RateLimitOptions) => RateLimitResult;
+/**
+ * `RunActionOptions` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+ * @experimental
+ */
+interface RunActionOptions extends ActionCallOptions {
+  /**
+   * Client to run the action on. Defaults to the injected `LUNORA_CLIENT`.
+   * Because actions usually fire from event handlers — which run *outside* an
+   * injection context — capture the client once (`injectLunoraClient()` in a
+   * field) and pass it here, or call `client.action(...)` directly.
+   */
+  client?: LunoraClient;
+}
+/**
+ * Run a Lunora action and resolve with the server result (rejects on failure).
+ *
+ * The sibling of `mutate`, and a plain function for the same reason: Angular's
+ * adapter models writes as calls rather than reactive handles, because they fire
+ * from event handlers where a signal-returning primitive has nothing to bind to.
+ * The other adapters return a reactive `{ call, pending, … }` handle because
+ * their idioms make that natural; this one does not.
+ *
+ * Unlike `mutate` there are no `optimistic` / `optimisticUpdate` 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.
+ *
+ * ```ts
+ * private readonly client = injectLunoraClient();
+ * verify = () => runAction(api.commands.run, { command: "lunora", args: ["verify"] }, { client: this.client });
+ * ```
+ *
+ * When called from within an injection context you may omit `client` and let it
+ * resolve from the injector.
+ * @experimental
+ */
+declare const runAction: <F extends FunctionReference>(reference: F, args: ArgsOf<F>, options?: RunActionOptions) => Promise<ReturnOf<F>>;
 /**
  * The lifecycle of a stream the primitive is observing.
  * @experimental
@@ -1082,6 +1202,13 @@ interface StreamOptions {
    * `inject(DestroyRef)` — the calling component/service.
    */
   destroyRef?: DestroyRef;
+  /**
+   * 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;
   /** Route to a specific shard when the target function is `.shardBy(...)`-partitioned. */
@@ -1109,8 +1236,8 @@ interface StreamResult<T> {
  * 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.
+ * `DestroyRef` fires. Nothing opens on the Angular server platform (SSR). The
+ * Angular counterpart to React's `useStream`, re-expressed with signals.
  *
  * Call from an injection context (component/service field or constructor):
  * ```ts
@@ -1131,6 +1258,14 @@ interface SubscriptionOptions {
    * `inject(DestroyRef)` — the calling component/service.
    */
   destroyRef?: DestroyRef;
+  /**
+   * `Injector` to create the reactive-args `effect()` from. Only needed when
+   * `args` is a function/`Signal` AND `subscription` is called outside an
+   * injection context (an explicit `destroyRef` is also being passed).
+   * Defaults to the ambient injection context. Unused for the static `args`
+   * form, which never creates an `effect()`.
+   */
+  injector?: Injector;
   /**
    * Called when the subscription errors after the initial attach. Without it,
    * a post-attach failure is dropped silently.
@@ -1164,9 +1299,13 @@ interface SubscriptionResult<T> {
  * ```ts
  * readonly stream = subscription(api.events.stream, { roomId: "general" });
  * ```
+ *
+ * `args` also accepts a function/`Signal` to make the subscription reactive —
+ * an args change tears the old subscription down and opens a fresh one for the
+ * new args. A static (plain object) `args` resolves once and never re-runs.
  * @experimental
  */
-declare const subscription: <F extends FunctionReference>(reference: F, args: ArgsOf<F> | "skip", options?: SubscriptionOptions) => SubscriptionResult<ReturnOf<F>>;
+declare const subscription: <F extends FunctionReference>(reference: F, args: ArgsOf<F> | "skip" | (() => ArgsOf<F> | "skip"), options?: SubscriptionOptions) => SubscriptionResult<ReturnOf<F>>;
 /**
  * Browser Web Audio subsystems for `voiceAgent` — the default microphone capture
  * and speaker playback implementations injected into the primitive via its
@@ -1205,8 +1344,24 @@ interface MicrophoneConfig {
   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;
+  /**
+   * `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). */
@@ -1225,9 +1380,9 @@ type CreateSpeaker = (config: {
   audioFormat: VoiceAudioFormat;
 }) => VoiceSpeaker;
 /**
- * The `agents.&lt;name>Voice` reference codegen emits for a voice-enabled agent — a
+ * 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.&lt;name>Voice` type-checks.
+ * generated member, so passing `api.agents.<name>Voice` type-checks.
  * @experimental
  */
 type VoiceReference = FunctionReference<"stream", {
@@ -1265,7 +1420,11 @@ interface VoiceAgentOptions {
    * 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)`. */
+  /**
+   * 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;
@@ -1282,9 +1441,13 @@ interface VoiceAgentOptions {
   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. */
+  /**
+   * The thread to converse on — shared with the agent's text turns. A plain
+   * value, or a `Signal`/getter resolved afresh every time a call opens — the
+   * reactive-args form the package's other primitives take.
+   */
+  threadKey: (() => string) | string;
+  /** The generated `api.agents.<name>Voice` reference — identifies the voice DO endpoint. */
   voice: VoiceReference;
 }
 /**
@@ -1320,7 +1483,7 @@ interface VoiceAgentResult {
  * 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`
+ * `audioLevel`) to Angular signals. Pass the generated `api.agents.<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
@@ -1336,4 +1499,20 @@ interface VoiceAgentResult {
  * @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 AuthGateResult, 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, authGate, connectionStatus, flag, flags, hydratePreloaded, infiniteQuery, injectLunoraClient, liveQuery, mutate, mutator, paginatedQuery, presence, provideLunora, rateLimit, stream, subscription, voiceAgent };
+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 AuthGateResult, type AuthOptions, type AuthResult, type ConnectionStatusOptions, 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,
+/**
+ * The Angular adapter for Lunora.
+ *
+ * Thin, idiomatic glue over the framework-neutral `@lunora/client`. Angular
+ * signals map directly onto Lunora's per-subscription deltas, so a live query is
+ * just a `signal` the WebSocket writes to.
+ *
+ * `provideLunora` / `LUNORA_CLIENT` / `injectLunoraClient` are the injectable
+ * provider carrying one `LunoraClient` (opens its socket lazily), wired once in the
+ * application config. `liveQuery` is a live-query `signal` that opens a
+ * subscription and updates on every delta, torn down automatically on
+ * `DestroyRef.onDestroy`. `mutate` runs a mutation (optimistic updates + offline
+ * queue pass through to the client). `connectionStatus` is a `signal` of the
+ * aggregate live-socket status.
+ */
+type ProvideLunoraOptions, type RateLimitOptions, type RateLimitResult, type RunActionOptions, 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, authGate, connectionStatus, flag, flags, hydratePreloaded, infiniteQuery, injectLunoraClient, liveQuery, mutate, mutator, paginatedQuery, presence, provideLunora, rateLimit, runAction, stream, subscription, voiceAgent };