@lunora/angular 1.0.0-alpha.26 → 1.0.0-alpha.260

package/dist/index.d.ts

@@ -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, LiveTopicOptions as LiveTopicOptions$1, LiveTopicRef, LiveStreamSubscribeError, MutationCallOptions, OnlineOnlyOption, 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;
@@ -51,8 +56,8 @@ interface AgentChatMessage {
   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";
+  /** Approval or secret-request lifecycle marker on a human-in-the-loop tool message. */
+  status?: "approved" | "awaiting_approval" | "awaiting_secret" | "rejected";
   toolCallId?: string;
   toolCalls?: ReadonlyArray<{
     id: string;
@@ -136,6 +141,12 @@ 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.<name>.run(...)`. Called with `{ threadKey, input }` merged with
@@ -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`. */
@@ -189,7 +202,7 @@ type AgentMessagesReference$1 = FunctionReference<"query", {
 }, ReadonlyArray<Record<string, unknown>>>;
 /** The `agents:agentResolveApproval` reference — resolves a human-in-the-loop tool approval. */
 type AgentApprovalReference = FunctionReference<"mutation", {
-  decision: "approve" | "reject";
+  decision: "approve" | "approve_for_thread" | "reject";
   instanceId: string;
   note?: string;
   threadKey: string;
@@ -197,10 +210,41 @@ type AgentApprovalReference = FunctionReference<"mutation", {
 }, {
   resolved: boolean;
 }>;
+/** The `agents:agentSupplySecret` reference — stores a person's value for a paused `requestSecretTool` call. */
+type AgentSupplySecretReference = FunctionReference<"mutation", {
+  secret: string;
+  threadKey: string;
+  toolCallId: string;
+}, {
+  resolved: boolean;
+}>;
+/** The `agents:agentDeclineSecret` reference — refuses a paused `requestSecretTool` call. */
+type AgentDeclineSecretReference = FunctionReference<"mutation", {
+  threadKey: string;
+  toolCallId: string;
+}, {
+  resolved: boolean;
+}>;
 /** The `agents:agentThread` reference — live thread status + in-flight `instanceId`. */
 type AgentThreadReference = FunctionReference<"query", {
   key: string;
 }, Record<string, unknown> | undefined>;
+/** A tool approved for the rest of a thread, as `agents:agentApprovalGrants` lists it. */
+interface AgentApprovalGrant {
+  createdAt: number;
+  toolName: string;
+}
+/** The `agents:agentApprovalGrants` reference — live thread-scoped approval grants. */
+type AgentApprovalGrantsReference = FunctionReference<"query", {
+  key: string;
+}, ReadonlyArray<AgentApprovalGrant>>;
+/** The `agents:agentRevokeApprovalGrant` reference — removes a thread-scoped approval grant. */
+type AgentRevokeApprovalGrantReference = FunctionReference<"mutation", {
+  threadKey: string;
+  toolName: string;
+}, {
+  revoked: boolean;
+}>;
 /**
  * An app stream reference that tees the agent's in-flight live events, keyed by
  * thread. Carries token deltas and — since `ctx.reportProgress` rides the same
@@ -218,8 +262,12 @@ type AgentTokenStreamReference = FunctionReference<"stream", {
  */
 interface AgentChatApi {
   agents: {
+    agentApprovalGrants: AgentApprovalGrantsReference;
+    agentDeclineSecret: AgentDeclineSecretReference;
     agentMessages: AgentMessagesReference$1;
     agentResolveApproval: AgentApprovalReference;
+    agentRevokeApprovalGrant: AgentRevokeApprovalGrantReference;
+    agentSupplySecret: AgentSupplySecretReference;
     agentThread: AgentThreadReference;
   };
 }
@@ -246,6 +294,12 @@ interface AgentChatOptions {
   destroyRef?: DestroyRef;
   /** History depth forwarded to `agents:agentMessages`. */
   limit?: number;
+  /**
+   * Called when the live history, thread, or grants subscription reports an error (a
+   * session expiry, an RLS denial). Without it — and without reading `error` —
+   * such a failure is invisible and `messages` / `status` are cleared until a later frame arrives.
+   */
+  onError?: SubscriptionErrorCallback;
   /**
    * The app mutation that starts (or continues) a run — a thin wrapper over
    * `ctx.agents.<name>.run(...)`. Called with `{ threadKey, input }` merged with
@@ -268,27 +322,47 @@ interface AgentChatOptions {
  * @experimental
  */
 interface AgentChatResult {
+  /** The tools approved for the rest of this thread, live. Empty until the grants subscription answers. */
+  approvalGrants: Signal<ReadonlyArray<AgentApprovalGrant>>;
   /** Approve a paused human-in-the-loop tool call (optionally with a note). */
   approve: (toolCallId: string, note?: string) => Promise<void>;
+  /**
+   * Approve a paused tool call and grant that tool for the rest of the thread, so
+   * later calls to it run without pausing. Undo with {@link AgentChatResult.revokeGrant}.
+   */
+  approveForThread: (toolCallId: string, note?: string) => Promise<void>;
   /**
    * Terminate the in-flight run and mark its thread `"cancelled"`. Resolves as a
    * no-op when no `cancel` mutation was supplied or no run is in flight.
    */
   cancel: () => Promise<void>;
+  /** Refuse a paused `requestSecretTool` call: the run resumes with a "declined" result. */
+  declineSecret: (toolCallId: string) => Promise<void>;
+  /** The history, thread, or grants subscription's last error, or `undefined`. */
+  error: 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). */
   reject: (toolCallId: string, note?: string) => Promise<void>;
+  /** Remove a thread-scoped approval grant so the tool's gate applies again to later calls. */
+  revokeGrant: (toolName: string) => Promise<void>;
   /** Start (or continue) a run with a user message; extra args merge over `sendArgs`. Appends an optimistic user turn. */
   send: (input: string, args?: Record<string, unknown>) => Promise<void>;
   /** The live thread status, or `undefined` before the thread exists. */
   status: Signal<AgentThreadStatus | undefined>;
   /** The in-flight turn's streamed text — live-only, empty once the turn persists to `messages`. */
   streamingText: Signal<string>;
+  /**
+   * Give a paused `requestSecretTool` call its value. Always sent online-only: the
+   * value is never queued, persisted or replayed, and the call rejects with
+   * `OFFLINE_NOT_QUEUED` while the connection is down. The service keeps no copy;
+   * a failure rethrows the original error.
+   */
+  supplySecret: (toolCallId: string, secret: string) => Promise<void>;
 }
 /**
  * A first-class agent chat surface: live durable history + in-flight token
- * streaming + the send / approve / reject / cancel writes, keyed by `threadKey` —
+ * streaming + the send / approve / reject / secret / 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:
@@ -418,7 +492,7 @@ interface AgentToolEventsOptions {
    * 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.
+   * lifecycle (call / result / awaiting-approval / awaiting-secret) is returned.
    */
   stream?: AgentLiveStreamReference;
   /** The thread whose tool activity to observe. */
@@ -426,7 +500,7 @@ interface AgentToolEventsOptions {
 }
 /**
  * A single tool-lifecycle event for a thread. The durable arms
- * (`call`/`result`/`awaiting-approval`) are derived from `agents:agentMessages`
+ * (`call`/`result`/`awaiting-approval`/`awaiting-secret`) are derived from `agents:agentMessages`
  * and carry the persisted `seq`; the ephemeral `progress` arm comes live off the
  * stream and has no `seq`. Discriminate on `type`.
  * @experimental
@@ -453,6 +527,11 @@ type AgentToolEvent = {
   toolCallId?: string;
   toolName?: string;
   type: "awaiting-approval";
+} | {
+  seq: number;
+  toolCallId?: string;
+  toolName?: string;
+  type: "awaiting-secret";
 };
 /**
  * `AgentToolEventsResult` is part of the experimental `@lunora/angular` API and may change without a major version bump.
@@ -502,6 +581,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 +614,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 +712,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 +728,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 +739,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 +764,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 +772,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 +797,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 +815,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 +844,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 +887,78 @@ 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" | (() => ArgsOf<F> | "skip"), options?: LiveQueryOptions) => Signal<ReturnOf<F> | undefined>;
+/**
+ * `LiveTopicOptions` is part of the experimental `@lunora/angular` API and may change without a major version bump.
+ * @experimental
+ */
+interface LiveTopicOptions<Payload = unknown> extends Omit<LiveTopicOptions$1<Payload>, "sessionKey" | "shardKey"> {
+  /**
+   * The client the stream's route is resolved against. Defaults to `LUNORA_CLIENT`, read in the
+   * ambient injection context, so pass it when calling outside one (with an explicit `destroyRef`).
+   */
+  client?: LunoraClient;
+  /**
+   * `DestroyRef` whose `onDestroy` tears the subscription down. Defaults to
+   * `inject(DestroyRef)` — the calling component/service.
+   */
+  destroyRef?: DestroyRef;
+  /**
+   * `Injector` to create the reactive-args `effect()` from. Only needed when the
+   * topic is a function AND `liveTopic` is called outside an injection context
+   * with an explicit `destroyRef`. Unused for the static form.
+   */
+  injector?: Injector;
+  /**
+   * Partitions the shared live connection, as `sessionKey` does on `subscribeLiveTopic`: a changed value opens a new
+   * connection and closes the old one. Pass a signal (or any function) to make it reactive, e.g. to move to a new
+   * key on sign-out.
+   */
+  sessionKey?: string | (() => string | undefined);
+  /**
+   * Follow the topic on this shard, as `shardKey` does on the other adapters. Pass a signal (or any function) when the
+   * shard comes from an input or other state that changes: a new value reopens the subscription on the new shard.
+   */
+  shardKey?: string | (() => string | undefined);
+}
+/**
+ * Follow one live topic on the connection shared by its stream's route, and mirror its
+ * payloads into an Angular `signal`. Pass the reference `_generated/live.ts` hands out
+ * (`live.posts.post({ postId })`); the route is resolved against the injected `LunoraClient`,
+ * and `lastEvent` and `onEvent` are typed by the payload the topic declares.
+ *
+ * `lastEvent` reads `undefined` until the first event lands; `error` carries the
+ * shard's refusal of the subscription. The subscription is torn down when the
+ * owning `DestroyRef` fires, so there is no leaked subscriber.
+ *
+ * ```ts
+ * export class PostComponent {
+ *     readonly postId = input.required<string>();
+ *
+ *     readonly comments = liveTopic(() => live.posts.post({ postId: this.postId() }));
+ * }
+ * ```
+ *
+ * Pass a function when the topic reads a signal, as above: an input is not bound while a field
+ * initializer runs, so a plain reference would read `this.postId` too early. A new topic, or a new
+ * `sessionKey` or `shardKey` signal value, resubscribes, while a new `onEvent` / `onError` identity is read at
+ * call time and does not reopen the subscription.
  * @experimental
  */
-declare const liveQuery: <F extends FunctionReference>(reference: F, args: ArgsOf<F> | "skip", options?: LiveQueryOptions) => Signal<ReturnOf<F> | undefined>;
+declare const liveTopic: <Payload>(topic: LiveTopicRef<Payload> | (() => LiveTopicRef<Payload>), options?: LiveTopicOptions<Payload>) => {
+  error: Signal<LiveStreamSubscribeError | undefined>;
+  lastEvent: Signal<Payload | undefined>;
+};
 /**
  * `MutateOptions` is part of the experimental `@lunora/angular` API and may change without a major version bump.
  * @experimental
@@ -822,7 +991,7 @@ interface MutateOptions<F extends FunctionReference> extends MutationCallOptions
  * resolve from the injector.
  * @experimental
  */
-declare const mutate: <F extends FunctionReference>(reference: F, args: ArgsOf<F>, options?: MutateOptions<F>) => Promise<ReturnOf<F>>;
+declare const mutate: <F extends FunctionReference>(reference: F, args: ArgsOf<F>, options?: MutateOptions<F> & OnlineOnlyOption<F>) => Promise<ReturnOf<F>>;
 /**
  * `MutatorResult` is part of the experimental `@lunora/angular` API and may change without a major version bump.
  * @experimental
@@ -877,6 +1046,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 +1063,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 +1084,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 +1114,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 +1132,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 +1171,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 +1190,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 +1267,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 +1321,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 +1355,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 +1377,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 +1418,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 +1463,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). */
@@ -1265,7 +1539,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,8 +1560,12 @@ 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 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;
 }
@@ -1336,4 +1618,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 AgentApprovalGrant, 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 LiveTopicOptions, 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, liveTopic, mutate, mutator, paginatedQuery, presence, provideLunora, rateLimit, runAction, stream, subscription, voiceAgent };