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

package/dist/index.d.ts

@@ -1,26 +1,74 @@
-import { LunoraClient, FunctionReference, User, ConnectionStatus, ArgsOf, MutationCallOptions, ReturnOf, MutatorHandle, Preloaded } from '@lunora/client';
-export type { ArgsOf, FunctionReference, MutatorHandle, MutatorTransaction, OptimisticUpdate, Preloaded, ReturnOf, Unsubscribe } from '@lunora/client';
-import { Context, Accessor, JSX } from 'solid-js';
+import { LunoraClient, FunctionReference, ArgsOf, ActionCallOptions, ReturnOf, SubscriptionErrorCallback, User, ConnectionStatus, LiveStreamSubscribeError, LiveTopicRef, LiveTopicOptions, MutationCallOptions, OnlineOnlyOption, MutatorHandle, SubscriptionError, Preloaded } from '@lunora/client';
+export type { ArgsOf, FunctionReference, MutatorHandle, MutatorTransaction, OptimisticUpdate, Preloaded, ReturnOf, SubscriptionError, SubscriptionErrorCallback, Unsubscribe } from '@lunora/client';
+import { Context, Accessor } from 'solid-js';
+import { AuthStatus } from '@lunora/client/auth';
 import { PaginationStatus } from '@lunora/client/pagination';
 import { RateLimitStatus, RateLimitConfig } from '@lunora/ratelimit';
 /**
  * Solid context carrying the framework-neutral {@link LunoraClient}. Every
  * reactive primitive in this adapter (`createQuery`, `createMutation`,
  * `hydratePreloaded`) reads the client from here, so a single
- * `<LunoraProvider client={…}>` at the root of the tree wires the whole app.
+ * `<LunoraProvider client={…}>` at the root of the tree wires the whole app.
  *
  * Defaults to `undefined` so {@link useLunora} can throw a helpful error when a
- * primitive is used outside a provider rather than dereferencing it.
+ * primitive is used outside a provider rather than dereferencing it. Solid 2
+ * refuses to hand back an `undefined` default at all — see {@link useLunora}.
  */
 declare const LunoraContext: Context<LunoraClient | undefined>;
 /**
- * Read the {@link LunoraClient} from the nearest `&lt;LunoraProvider>`.
+ * Read the {@link LunoraClient} from the nearest `<LunoraProvider>`.
  *
  * Throws when called outside a provider — the client is required to open the
  * HTTP/WS transport, so there is no sensible fallback. The React adapter's
  * `useLunora` has the same contract.
  */
 declare const useLunora: () => LunoraClient;
+interface ActionHandle<F extends FunctionReference> {
+  /** Invoke the action. Resolves with the server result; rejects on failure. */
+  call: (args: ArgsOf<F>, options?: ActionCallOptions) => Promise<ReturnOf<F>>;
+  /** The latest invocation's resolved value, or `undefined` before the first success. */
+  data: Accessor<ReturnOf<F> | undefined>;
+  /** The latest invocation's error, or `undefined`. */
+  error: Accessor<Error | undefined>;
+  /** `true` while any invocation from this handle is in flight (ref-counted, so overlapping calls compose). */
+  pending: Accessor<boolean>;
+  /** Clear `data`/`error` back to idle. */
+  reset: () => void;
+}
+/**
+ * The transport surface {@link createAction} actually needs — just
+ * `client.action`. Narrowed so the primitive can be exercised against a stub in
+ * tests without constructing a full `LunoraClient`.
+ */
+interface ActionClient<F extends FunctionReference> {
+  action: (function_: F, args: ArgsOf<F>, options?: ActionCallOptions) => Promise<ReturnOf<F>>;
+}
+/**
+ * Build an action handle bound to an explicit client. Internal seam used by the
+ * provider-bound {@link createAction}; exported for tests that inject a stub.
+ * The ref-counted pending + error-normalize orchestration is the shared
+ * `createCallRunner` from `@lunora/client`; only the reactive sinks (Solid
+ * signals) are adapter-specific.
+ *
+ * `data`/`error` follow the adapter-wide contract: both track the LATEST
+ * invocation (an earlier call settling later cannot clobber a newer one), a
+ * success clears `error`, and a failure leaves the previous `data` in place.
+ * `reset()` clears both; it does not cancel an in-flight call.
+ */
+declare const createActionForClient: <F extends FunctionReference>(client: ActionClient<F>, function_: F) => ActionHandle<F>;
+/**
+ * Returns a reactive handle `{ call, pending, data, error, reset }` for the
+ * given action reference, bound to the `LunoraClient` from the nearest
+ * `<LunoraProvider>`.
+ *
+ * **Narrower than `createMutation` on purpose:** no `optimistic` /
+ * `optimisticUpdate` call options. An optimistic update patches the subscription
+ * cache on the assumption a write will land; an action is not a write — it runs
+ * in the Worker, may call a third party, and has no declared effect on any
+ * query. Offering the option would imply a rollback guarantee nothing can
+ * honour.
+ */
+declare const createAction: <F extends FunctionReference>(function_: F) => ActionHandle<F>;
 /**
  * The lifecycle status stored on an agent thread. Client-safe mirror of
  * `@lunora/agent`'s `AgentThreadStatus` — re-declared here (rather than imported)
@@ -37,8 +85,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;
@@ -49,7 +101,7 @@ interface AgentThreadRecord {
   updatedAt?: number;
 }
 /** A plain value or a Solid accessor of it — matching `createQuery`'s reactive-args contract. */
-type MaybeAccessor$1<T> = Accessor<T> | T;
+type MaybeAccessor<T> = Accessor<T> | T;
 /**
  * The `agents.agentThread` reference the primitive subscribes to for live thread
  * state (status + the in-flight `instanceId`). A structural subset of the
@@ -68,21 +120,27 @@ interface CreateAgentOptions {
   api: CreateAgentApi;
   /**
    * 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 CreateAgentResult.cancel} is a
    * no-op.
    */
   cancel?: FunctionReference<"mutation">;
+  /**
+   * Called when the live thread subscription reports an error (a session
+   * expiry, an RLS denial). Without it — and without reading `error` — such a
+   * failure is invisible and `thread` / `status` are cleared until a later frame arrives.
+   */
+  onError?: SubscriptionErrorCallback;
   /**
    * The app mutation that starts (or continues) a run — a thin wrapper over
-   * `ctx.agents.&lt;name>.run(...)`. Called with `{ threadKey, input }` merged with
+   * `ctx.agents.<name>.run(...)`. Called with `{ threadKey, input }` merged with
    * {@link CreateAgentOptions.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 — a plain value or accessor (an accessor re-subscribes on change). */
-  threadKey: MaybeAccessor$1<string>;
+  threadKey: MaybeAccessor<string>;
 }
 interface CreateAgentResult {
   /**
@@ -90,6 +148,8 @@ interface CreateAgentResult {
    * 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: Accessor<Error | undefined>;
   /** `true` while a `run` invocation is in flight. */
   pending: Accessor<boolean>;
   /** Start (or continue) a run with a user message; extra args merge over `runArgs`. */
@@ -108,7 +168,7 @@ interface CreateAgentResult {
  * `createAgentChat`.
  *
  * `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. `threadKey` may be an accessor — a changing
  * key re-subscribes to the new thread.
  */
@@ -130,8 +190,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;
@@ -185,7 +245,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;
@@ -193,10 +253,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
@@ -212,8 +303,12 @@ type AgentTokenStreamReference = FunctionReference<"stream", {
  */
 interface CreateAgentChatApi {
   agents: {
+    agentApprovalGrants: AgentApprovalGrantsReference;
+    agentDeclineSecret: AgentDeclineSecretReference;
     agentMessages: AgentMessagesReference$1;
     agentResolveApproval: AgentApprovalReference;
+    agentRevokeApprovalGrant: AgentRevokeApprovalGrantReference;
+    agentSupplySecret: AgentSupplySecretReference;
     agentThread: AgentThreadReference;
   };
 }
@@ -222,16 +317,22 @@ interface CreateAgentChatOptions {
   api: CreateAgentChatApi;
   /**
    * 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 CreateAgentChatResult.cancel} is
    * a no-op.
    */
   cancel?: FunctionReference<"mutation">;
   /** History depth forwarded to `agents:agentMessages`. */
   limit?: number;
+  /**
+   * Called when the live history, thread, or grants subscription reports an error (a
+   * session expiry, an RLS denial). Without it — and without reading `error` —
+   * such a failure is invisible and `messages` / `status` are cleared until a later frame arrives.
+   */
+  onError?: SubscriptionErrorCallback;
   /**
    * The app mutation that starts (or continues) a run — a thin wrapper over
-   * `ctx.agents.&lt;name>.run(...)`. Called with `{ threadKey, input }` merged with
+   * `ctx.agents.<name>.run(...)`. Called with `{ threadKey, input }` merged with
    * {@link CreateAgentChatOptions.sendArgs} and the per-call args.
    */
   send: FunctionReference<"mutation">;
@@ -244,30 +345,50 @@ interface CreateAgentChatOptions {
    */
   stream?: AgentTokenStreamReference;
   /** The thread to observe and continue — a plain value or accessor (an accessor re-subscribes on change). */
-  threadKey: MaybeAccessor$1<string>;
+  threadKey: MaybeAccessor<string>;
 }
 interface CreateAgentChatResult {
+  /** The tools approved for the rest of this thread, live. Empty until the grants subscription answers. */
+  approvalGrants: Accessor<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 CreateAgentChatResult.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: Accessor<Error | undefined>;
   /** Durable thread history (oldest first) plus any un-acknowledged optimistic user turns. */
   messages: Accessor<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: Accessor<AgentThreadStatus | undefined>;
   /** The in-flight turn's streamed text — live-only, empty once the turn persists to `messages`. */
   streamingText: Accessor<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 primitive 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 Solid counterpart to React's `useAgentChat`, re-expressed with signals.
  *
  * It composes the existing primitives rather than adding transport:
@@ -305,7 +426,7 @@ interface CreateAgentStateOptions {
   /** The generated `api` — its `agents.agentState` query drives live thread state. */
   api: CreateAgentStateApi;
   /** The thread whose synced state to observe — a plain value or accessor (an accessor re-subscribes on change). */
-  threadKey: MaybeAccessor$1<string>;
+  threadKey: MaybeAccessor<string>;
 }
 interface CreateAgentStateResult<T> {
   /** The subscription error, if the live channel reported one. */
@@ -361,15 +482,15 @@ interface CreateAgentToolEventsOptions {
    * Optional live event stream — the same app stream function `createAgentChat`
    * 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.
+   * durable lifecycle (call / result / awaiting-approval / awaiting-secret) is returned.
    */
   stream?: AgentLiveStreamReference;
   /** The thread whose tool activity to observe — a plain value or accessor (an accessor re-subscribes on change). */
-  threadKey: MaybeAccessor$1<string>;
+  threadKey: MaybeAccessor<string>;
 }
 /**
  * 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`.
  */
@@ -395,6 +516,11 @@ type AgentToolEvent = {
   toolCallId?: string;
   toolName?: string;
   type: "awaiting-approval";
+} | {
+  seq: number;
+  toolCallId?: string;
+  toolName?: string;
+  type: "awaiting-secret";
 };
 interface CreateAgentToolEventsResult {
   /**
@@ -419,8 +545,41 @@ interface CreateAgentToolEventsResult {
  * + approvals) use `createAgentChat`; this primitive is the tool-observability slice.
  */
 declare const createAgentToolEvents: (options: CreateAgentToolEventsOptions) => CreateAgentToolEventsResult;
+/**
+ * Children accepted by this adapter's components.
+ *
+ * Structurally identical to Solid 2.0's `Element`, which is in turn a widening
+ * of 1.x's `JSX.Element` (a DOM `Node` satisfies `object` with no
+ * `call`/`apply`/`bind`). Children are contravariant, so one union that accepts
+ * both majors' element types is enough — no `any` required here.
+ */
+type SolidChildren = SolidChildrenArray | boolean | null | number | (object & {
+  readonly apply?: never;
+  readonly bind?: never;
+  readonly call?: never;
+}) | (string & {}) | undefined;
+interface SolidChildrenArray extends Array<SolidChildren> {}
+/**
+ * The return type of this adapter's components.
+ *
+ * Deliberately `any`, and the one place in the package where that is the right
+ * answer. TypeScript checks a component's return type against the *renderer's*
+ * `JSX.Element`, and the two majors define that incompatibly — 1.x's is rooted
+ * in the DOM `Node` interface, 2.0's in an opaque `RenderedElement`. Neither is
+ * assignable to the other, so no concrete type satisfies both, and a structural
+ * union (as used for {@link SolidChildren}) fails in the return position. `any`
+ * is what lets one set of `.d.ts` files type-check inside a 1.x app and a 2.x
+ * app alike.
+ */
+type SolidElement = any;
 interface UseAuthResult {
   setToken: (token: string | null) => void;
+  /**
+   * The resolved auth state. Branch on this, not on `user() === null` — see the
+   * contract in `@lunora/client/auth`; `user` is `null` both when signed out
+   * and when a held credential's identity could not be resolved.
+   */
+  status: Accessor<AuthStatus>;
   token: Accessor<string | null>;
   user: Accessor<User | null>;
 }
@@ -432,23 +591,29 @@ interface UseAuthResult {
  */
 declare const createAuth: () => UseAuthResult;
 interface AuthGateProps {
-  children: JSX.Element;
+  children: SolidChildren;
 }
+/** An auth-gate component: renders its children only while the gate's condition holds. */
+type AuthGate = (props: AuthGateProps) => SolidElement;
 /**
- * Render `children` only after authentication has settled and a token + user
- * are both present.
+ * Render `children` once authentication has settled in the caller's favour — a
+ * credential is held and nothing has contradicted it.
+ *
+ * Gated on the shared `AuthStatus` contract in `@lunora/client/auth`, not on
+ * `user() !== null`: an unreachable identity endpoint leaves `user` at `null`
+ * while the credential is still perfectly valid.
  */
-declare const Authenticated: (props: AuthGateProps) => JSX.Element;
+declare const Authenticated: AuthGate;
 /**
- * Render `children` while authentication is still in progress — token is set
- * but the user has not yet resolved.
+ * Render `children` while authentication is still in progress — a credential is
+ * held and the first identity resolve has not come back yet.
  */
-declare const AuthLoading: (props: AuthGateProps) => JSX.Element;
+declare const AuthLoading: AuthGate;
 /**
- * Render `children` only when auth has settled and no token is present (the
- * signed-out state).
+ * Render `children` only when auth has settled and there is no session — no
+ * credential, or the server answered that the credential has none.
  */
-declare const Unauthenticated: (props: AuthGateProps) => JSX.Element;
+declare const Unauthenticated: AuthGate;
 /**
  * Reactive accessor of the client's aggregate live-socket status across all
  * shard connections. Reads the current status synchronously and updates on
@@ -456,18 +621,20 @@ declare const Unauthenticated: (props: AuthGateProps) => JSX.Element;
  * fine-grained signals mean only the components that read the accessor
  * re-render. The Solid equivalent of `@lunora/react`'s `useConnectionStatus`.
  *
- * The status listener is torn down via `onCleanup` when the owning reactive
- * scope disposes (component unmount). Call inside a component / reactive root.
+ * The listener is registered at **mount**, not in the component body, because
+ * `onConnectionStatus` invokes it synchronously on subscribe: Solid 2 rejects a
+ * signal write inside an owned scope (`REACTIVE_WRITE_IN_OWNED_SCOPE`) and — since
+ * the throw escapes render — halts the reactive system for the whole page, not
+ * just this component. Nothing is missed by waiting: the initial value comes
+ * from `client.connectionStatus()`, and the immediate callback re-syncs at
+ * mount. Torn down when the owning scope disposes. Call inside a component /
+ * reactive root.
  */
 declare const createConnectionStatus: () => Accessor<ConnectionStatus>;
-/** A targeting context merged on top of the app's default (`defineFlags({ identify })`). */
-type FlagContext = Record<string, unknown>;
 /** The value kinds a flag resolves to — OpenFeature's boolean / number / string / structured (JSON) flags. */
 type FlagValue = boolean | number | string | {
   [key: string]: unknown;
 } | unknown[] | null;
-/** A plain value or a Solid accessor of it — matching `createQuery`'s reactive-args contract. */
-type MaybeAccessor<T> = Accessor<T> | T;
 /**
  * Subscribe to a single feature flag and return a reactive accessor of its value.
  *
@@ -477,33 +644,64 @@ type MaybeAccessor<T> = Accessor<T> | T;
  * `defaultValue`'s runtime type, so `createFlag("dark", false)` reads a boolean
  * and `createFlag("hero", "control")` a string.
  *
- * `key` and `context` may be plain values or accessors; passing an accessor makes
- * the subscription reactive — when it changes the old subscription is torn down
- * (via `onCleanup`) and a fresh one opens. `context` supplies a per-call targeting
- * context merged on top of the app's default `identify` targeting key.
+ * `key` may be a plain value or an accessor; passing an accessor makes the
+ * subscription reactive — when it changes the old subscription is torn down (via
+ * `onCleanup`) and a fresh one opens.
+ *
+ * The reactive channel is public, so the server evaluates every flag under the
+ * socket's own verified identity — the targeting key your `defineFlags({
+ * identify })` derives — and accepts no client-supplied targeting context. For
+ * evaluation under a context you compute, call `ctx.flags.*` inside a query,
+ * mutation, or action and return the resolved value.
  *
  * Evaluation runs through whatever OpenFeature provider the app wired in
  * `lunora/flags.ts`; the read never throws — a provider error resolves the
  * default (the same fail-open contract as server-side `ctx.flags`).
  */
-declare const createFlag: <T extends FlagValue>(key: MaybeAccessor<string>, defaultValue: T, context?: MaybeAccessor<FlagContext | undefined>) => Accessor<T>;
+declare const createFlag: <T extends FlagValue>(key: MaybeAccessor<string>, defaultValue: T) => Accessor<T>;
 /**
  * Subscribe to several feature flags at once and return a reactive accessor of
  * the resolved record.
  *
  * Pass a record of `key → defaultValue`; each flag's kind is inferred from its
  * default, and the accessor reads the same-shaped record with resolved values
- * (the defaults until each evaluation lands). A single `context` applies to every
- * flag and may be an accessor. This is the batched form of {@link createFlag}.
+ * (the defaults until each evaluation lands). This is the batched form of
+ * {@link createFlag}, and evaluates under the socket's server-verified identity
+ * only. The flag set is fixed for the primitive's lifetime, so nothing here is
+ * reactive — the subscriptions open on mount and tear down on cleanup.
+ */
+declare const createFlags: <T extends Record<string, FlagValue>>(flags: T) => Accessor<T>;
+/**
+ * `createLiveTopic` — follow one live topic on the connection shared by its URL.
+ *
+ * A thin lifecycle wrapper over `subscribeLiveTopic` from `@lunora/client`: it
+ * subscribes when the owner mounts, unsubscribes on cleanup, and resubscribes when
+ * the topic or the connection options change. Callbacks are not part of that
+ * identity, so a new `onEvent` / `onError` never reopens the subscription.
+ */
+interface CreateLiveTopicResult<Payload = unknown> {
+  /** The shard's refusal of this subscription (403, 409, 429 and similar), or `undefined`. */
+  error: Accessor<LiveStreamSubscribeError | undefined>;
+  /** The last payload delivered on the topic, or `undefined` until the first event. */
+  lastEvent: Accessor<Payload | undefined>;
+}
+/**
+ * Follow the topic `topic` names on the live connection shared by its stream's route. Pass the
+ * reference `_generated/live.ts` hands out (`live.posts.post({ postId })`), plain or as an
+ * accessor; the route is resolved against the `LunoraClient` from the nearest `LunoraContext`,
+ * and `lastEvent` and `onEvent` are typed by the payload the topic declares.
+ *
+ * `options` may be a plain object or an accessor. The `onEvent` and `onError` callbacks are
+ * read at call time, so the latest identity is always the one invoked.
  */
-declare const createFlags: <T extends Record<string, FlagValue>>(flags: T, context?: MaybeAccessor<FlagContext | undefined>) => Accessor<T>;
+declare const createLiveTopic: <Payload>(topic: LiveTopicRef<Payload> | Accessor<LiveTopicRef<Payload>>, options?: LiveTopicOptions<Payload> | Accessor<LiveTopicOptions<Payload>>) => CreateLiveTopicResult<Payload>;
 interface MutationHandle<F extends FunctionReference> {
   /** The latest invocation's resolved value, or `undefined` before the first success. */
   data: Accessor<ReturnOf<F> | undefined>;
   /** The latest invocation's error, or `undefined`. */
   error: Accessor<Error | undefined>;
   /** Invoke the mutation. Resolves with the server result; rejects on failure. */
-  mutate: (args: ArgsOf<F>, options?: MutationCallOptions<unknown, unknown, ArgsOf<F>>) => Promise<ReturnOf<F>>;
+  mutate: (args: ArgsOf<F>, options?: MutationCallOptions<unknown, unknown, ArgsOf<F>> & OnlineOnlyOption<F>) => Promise<ReturnOf<F>>;
   /** `true` while any invocation from this handle is in flight (ref-counted, so overlapping calls compose). */
   pending: Accessor<boolean>;
   /** Clear `data`/`error` back to idle. */
@@ -515,20 +713,25 @@ interface MutationHandle<F extends FunctionReference> {
  * in tests without constructing a full `LunoraClient`.
  */
 interface MutationClient<F extends FunctionReference> {
-  mutation: (function_: F, args: ArgsOf<F>, options?: MutationCallOptions<unknown, unknown, ArgsOf<F>>) => Promise<ReturnOf<F>>;
+  mutation: (function_: F, args: ArgsOf<F>, options?: MutationCallOptions<unknown, unknown, ArgsOf<F>> & OnlineOnlyOption<F>) => Promise<ReturnOf<F>>;
 }
 /**
  * Build a mutation handle bound to an explicit client. Internal seam used by the
  * provider-bound {@link createMutation}; exported for tests that inject a stub.
  * The ref-counted pending + error-normalize orchestration is the shared
- * `createMutationRunner` from `@lunora/client`; only the reactive sinks (Solid
+ * `createCallRunner` from `@lunora/client`; only the reactive sinks (Solid
  * signals) are adapter-specific.
+ *
+ * `data`/`error` follow the adapter-wide contract: both track the LATEST
+ * invocation (an earlier call settling later cannot clobber a newer one), a
+ * success clears `error`, and a failure leaves the previous `data` in place.
+ * `reset()` clears both; it does not cancel an in-flight call.
  */
 declare const createMutationForClient: <F extends FunctionReference>(client: MutationClient<F>, function_: F) => MutationHandle<F>;
 /**
  * Returns a reactive handle `{ mutate, pending, data, error, reset }` for the
  * given mutation reference, bound to the `LunoraClient` from the nearest
- * `&lt;LunoraProvider>`.
+ * `<LunoraProvider>`.
  *
  * Optimistic updates stay client-owned: the `optimistic` / `optimisticUpdate`
  * call options pass straight through to `client.mutation`, which applies and
@@ -583,9 +786,18 @@ type PageItemOf<F extends FunctionReference> = ReturnOf<F> extends {
 interface CreatePaginatedQueryOptions {
   /** Page size for the first page (and the default for `loadMore`). */
   initialNumItems: number;
+  /** Called when a page subscription reports an error (also surfaced on the `error` accessor). */
+  onError?: SubscriptionErrorCallback;
   shardKey?: string;
 }
 interface CreatePaginatedQueryResult<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: Accessor<SubscriptionError | undefined>;
   /** `true` while the first page or a `loadMore` page is in flight. */
   isLoading: Accessor<boolean>;
   /** Request the next page. A no-op unless `status === "CanLoadMore"`. */
@@ -597,9 +809,13 @@ interface CreatePaginatedQueryResult<T> {
 interface CreateInfiniteQueryOptions {
   /** Page size for the first page (and the default for `fetchNextPage`). */
   initialNumItems: number;
+  /** Called when a page subscription reports an error (also surfaced on the `error` accessor). */
+  onError?: SubscriptionErrorCallback;
   shardKey?: string;
 }
 interface CreateInfiniteQueryResult<T> {
+  /** The last page subscription error, or `undefined` — see `CreatePaginatedQueryResult.error`. */
+  error: Accessor<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. */
@@ -665,6 +881,12 @@ interface CreatePresenceOptions<H extends HeartbeatReference, L extends ListPres
   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-mount id.
    * Pass a user/connection id to control deduping across tabs.
@@ -674,6 +896,8 @@ interface CreatePresenceOptions<H extends HeartbeatReference, L extends ListPres
   shardKey?: string;
 }
 interface CreatePresenceResult<L extends ListPresentReference> {
+  /** The `listPresent` subscription's last error, or `undefined`. */
+  error: () => SubscriptionError | undefined;
   /** The present members for the room. `undefined` until the first push. */
   present: () => ReturnOf<L> | undefined;
   /** This mount's session id (generated when not supplied). */
@@ -683,6 +907,12 @@ interface CreatePresenceResult<L extends ListPresentReference> {
 }
 declare const createPresence: <H extends HeartbeatReference, L extends ListPresentReference>(roomId: string, options: CreatePresenceOptions<H, L>) => CreatePresenceResult<L>;
 interface CreateQueryOptions {
+  /**
+   * Called when the server pushes a subscription-scoped error (an RLS denial, a
+   * query that starts failing server-side). Without a handler such an error has
+   * nowhere to go and the accessor simply freezes at its last good value.
+   */
+  onError?: SubscriptionErrorCallback;
   /** Route to a specific shard when the target function is `.shardBy(...)`-partitioned. */
   shardKey?: string;
 }
@@ -696,13 +926,18 @@ interface CreateQueryOptions {
  *
  * `args` may be a plain value or an accessor; passing an accessor makes the
  * subscription reactive — when the args change the old subscription is torn down
- * (via `onCleanup`) and a fresh one opens for the new args. Pass `"skip"` (or an
+ * (via `onCleanup`), the accessor resets to `undefined`, and a fresh one opens for
+ * the new args. Pass `"skip"` (or an
  * accessor returning `"skip"`) to short-circuit: no network call, no socket.
  *
  * ```tsx
  * const messages = createQuery(api.messages.list, () => ({ channelId: channelId() }));
- * return &lt;For each={messages()?.messages}>{(m) => &lt;li>{m.text}&lt;/li>}&lt;/For>;
+ * return <For each={messages()?.messages}>{(m) => <li>{m.text}</li>}</For>;
  * ```
+ *
+ * Pass `onError` to surface a subscription-scoped error the server pushes (an RLS
+ * denial, a query that starts failing server-side). Without it such an error is
+ * dropped and the accessor just freezes at its last good value.
  */
 declare const createQuery: <F extends FunctionReference>(function_: F, args: (ArgsOf<F> | "skip") | Accessor<ArgsOf<F> | "skip">, options?: CreateQueryOptions) => Accessor<ReturnOf<F> | undefined>;
 interface CreateRateLimitOptions {
@@ -749,6 +984,13 @@ interface CreateStreamResult<T> {
   status: Accessor<CreateStreamStatus>;
 }
 interface CreateStreamOptions {
+  /**
+   * Opt into resume-on-reconnect for a stream the server declared `durable`.
+   * The chunks already received are kept and the socket re-attaches to the same
+   * run, so a dropped connection mid-generation continues instead of surfacing
+   * `STREAM_DISCONNECTED`. Has no effect on an ephemeral stream.
+   */
+  durable?: boolean;
   /** Forwarded to `client.stream()` — caps the in-flight chunk buffer. */
   maxBuffer?: number;
   shardKey?: string;
@@ -772,8 +1014,13 @@ interface CreateSubscriptionResult<T> {
  * Subscribe to a reactive server push stream. Returns `{ data, error }`
  * accessors that update whenever the server emits. Passing `"skip"` as `args`
  * (or an accessor that resolves to `"skip"`) tears down the subscription.
+ *
+ * `onError` mirrors the other adapters' subscription primitives: it receives the
+ * raw wire-level subscription error (code included) alongside the normalised
+ * `error` accessor.
  */
 declare const createSubscription: <F extends FunctionReference>(function_: F, args: ArgsOf<F> | "skip" | Accessor<ArgsOf<F> | "skip">, options?: {
+  onError?: SubscriptionErrorCallback;
   shardKey?: string;
 }) => CreateSubscriptionResult<ReturnOf<F>>;
 /**
@@ -813,8 +1060,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). */
@@ -833,9 +1096,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.
  */
 type VoiceReference = FunctionReference<"stream", {
   threadKey: string;
@@ -863,7 +1126,11 @@ interface CreateVoiceAgentOptions {
    * 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;
@@ -876,8 +1143,8 @@ interface CreateVoiceAgentOptions {
   /** Input RMS below which audio counts as silence. Default `0.01`. */
   silenceThreshold?: number;
   /** The thread to converse on — shared with the agent's text turns. May be a plain value or accessor (resolved when the call opens). */
-  threadKey: MaybeAccessor$1<string>;
-  /** The generated `api.agents.&lt;name>Voice` reference — identifies the voice DO endpoint. */
+  threadKey: MaybeAccessor<string>;
+  /** The generated `api.agents.<name>Voice` reference — identifies the voice DO endpoint. */
   voice: VoiceReference;
 }
 interface CreateVoiceAgentResult {
@@ -909,7 +1176,7 @@ interface CreateVoiceAgentResult {
  * 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 Solid signals. Pass the generated `api.agents.&lt;name>Voice`
+ * `audioLevel`) to Solid signals. Pass the generated `api.agents.<name>Voice`
  * reference (never a string), matching `createAgentChat`'s reference-passing style.
  * The Solid counterpart to React's `useVoiceAgent`, re-expressed with signals; the
  * per-call connection lives in a closure variable (a primitive runs once per
@@ -929,23 +1196,37 @@ declare const createVoiceAgent: (options: CreateVoiceAgentOptions) => CreateVoic
  * returned accessor is seeded **synchronously** from `preloaded.value`, so the
  * very first read — during hydration — returns the server-rendered value with
  * no loading flash and no `Suspense` fallback (unlike `createResource`, which
- * always starts pending). After the component mounts, a WebSocket subscription
- * attaches in an effect and every subsequent server delta flows into the same
- * signal, so the UI goes live with zero refetch.
+ * always starts pending). Once the component mounts, a WebSocket subscription
+ * attaches and every subsequent server delta flows into the same signal, so the
+ * UI goes live with zero refetch.
  *
  * ```tsx
  * // route loader (server): const preloaded = await preloadQuery(client, api.messages.list, args);
  * const messages = hydratePreloaded(preloaded); // seeded from SSR, then live
- * return &lt;pre>{JSON.stringify(messages())}&lt;/pre>;
+ * return <pre>{JSON.stringify(messages())}</pre>;
  * ```
  *
- * Effects do not run on the server during SSR (Solid only runs them after
- * hydration), so the subscription is strictly client-side — the seed is the
- * only value the server render ever sees.
+ * Mount callbacks do not run on the server during SSR (both Solid majors defer
+ * them until after hydration), so the subscription is strictly client-side —
+ * the seed is the only value the server render ever sees.
+ *
+ * Pass `onError` to surface a subscription-scoped error the server pushes (a
+ * session expiry, an RLS denial). Without it such an error is dropped and the
+ * accessor keeps rendering the SSR snapshot as if it were live.
+ *
+ * The preloaded value was read for whoever was signed in when the page loaded.
+ * After a sign-out or user switch retires that identity
+ * (`client.identityEpoch() > 0`), every `hydratePreloaded` on the client (mounted
+ * then or later) stops using it and returns `undefined` until the live value
+ * arrives — matching `@lunora/react`'s `usePreloadedQuery`, hence the
+ * `Accessor<T | undefined>` type. The same holds under a `LunoraProvider` whose
+ * `client` was swapped: the value was preloaded for the first client.
  */
-declare const hydratePreloaded: <T>(preloaded: Preloaded<T>) => Accessor<T>;
+declare const hydratePreloaded: <T>(preloaded: Preloaded<T>, options?: {
+  onError?: SubscriptionErrorCallback;
+}) => Accessor<T | undefined>;
 interface LunoraProviderProps {
-  children: JSX.Element;
+  children: SolidChildren;
   /**
    * The framework-neutral transport. Build it once at the app root with
    * `new LunoraClient({ url })` (or `createServerClient` during SSR) and pass
@@ -967,11 +1248,46 @@ interface LunoraProviderProps {
  * const client = new LunoraClient({ url: window.location.origin });
  *
  * render(() => (
- *     &lt;LunoraProvider client={client}>
- *         &lt;App />
- *     &lt;/LunoraProvider>
+ *     <LunoraProvider client={client}>
+ *         <App />
+ *     </LunoraProvider>
  * ), root);
  * ```
+ *
+ * Swapping the `client` prop for a different instance **remounts the subtree**
+ * under the provider. Solid's providers read their value once, so the swap
+ * cannot be pushed into primitives that already resolved the client; instead
+ * every primitive below is disposed (its subscriptions on the old client torn
+ * down) and recreated against the new client, starting from `undefined` — no
+ * rows from the old client survive, and `hydratePreloaded` does not seed a value
+ * preloaded for the client the provider first rendered with (not even after
+ * swapping back to it). Local component state under the provider resets with
+ * it. Re-reading the same instance is a no-op.
+ *
+ * Written with `createComponent` rather than JSX on purpose. Solid 1.x and 2.0
+ * compile JSX against different runtimes (`solid-js/web` vs `@solidjs/web`), so
+ * a JSX source file would force this package to ship two builds; `createComponent`
+ * is exported from the `solid-js` root in both majors, and the provider component
+ * itself is resolved per-major by {@link providerOf}.
+ */
+declare const LunoraProvider: (props: LunoraProviderProps) => SolidElement;
+export { type ActionClient, type ActionHandle, type AgentApprovalGrant, type AgentChatMessage, type AgentLiveEvent, type AgentProgressEvent, type AgentThreadRecord, type AgentThreadStatus, type AgentTokenDelta, type AgentToolEvent, AuthLoading, Authenticated, type CreateAgentApi, type CreateAgentChatApi, type CreateAgentChatOptions, type CreateAgentChatResult, type CreateAgentOptions, type CreateAgentResult, type CreateAgentStateApi, type CreateAgentStateOptions, type CreateAgentStateResult, type CreateAgentToolEventsApi, type CreateAgentToolEventsOptions, type CreateAgentToolEventsResult, type CreateInfiniteQueryOptions, type CreateInfiniteQueryResult, type CreateLiveTopicResult, type CreatePaginatedQueryOptions, type CreatePaginatedQueryResult, type CreatePresenceOptions, type CreatePresenceResult, type CreateQueryOptions, type CreateRateLimitOptions, type CreateRateLimitResult, type CreateStreamOptions, type CreateStreamResult, type CreateStreamStatus, type CreateSubscriptionResult, type CreateVoiceAgentOptions, type CreateVoiceAgentResult, type FlagValue, type HeartbeatReference, type ListPresentReference, LunoraContext, LunoraProvider,
+/**
+ * SolidJS adapter for Lunora.
+ *
+ * Thin, idiomatic glue over the framework-neutral `@lunora/client`. Solid's
+ * fine-grained signals map directly onto Lunora's per-subscription deltas, so a
+ * live query is just a signal the WebSocket writes to. The adapter exposes
+ * `LunoraProvider` / `useLunora` (context carrying the `LunoraClient`),
+ * `createQuery` (a live query accessor that opens a subscription and updates on
+ * every delta), `createMutation` (an optimistic mutation handle), and
+ * `hydratePreloaded` (seed a query from an SSR `Preloaded` token synchronously —
+ * no loading flash — then attach the live subscription; the client half of
+ * PLAN4's "your loaders are live" reactive-loader handoff).
+ *
+ * Server-side preloading (`createServerClient`, `preloadQuery`) lives in the
+ * socket-free `@lunora/solid/server` entry (a re-export of `@lunora/client/ssr`, the
+ * framework-neutral server contract) — call it from your SolidStart route loader
+ * and hand the resulting `Preloaded` token to `hydratePreloaded`.
  */
-declare const LunoraProvider: (props: LunoraProviderProps) => JSX.Element;
-export { type AgentChatMessage, type AgentLiveEvent, type AgentProgressEvent, type AgentThreadRecord, type AgentThreadStatus, type AgentTokenDelta, type AgentToolEvent, AuthLoading, Authenticated, type CreateAgentApi, type CreateAgentChatApi, type CreateAgentChatOptions, type CreateAgentChatResult, type CreateAgentOptions, type CreateAgentResult, type CreateAgentStateApi, type CreateAgentStateOptions, type CreateAgentStateResult, type CreateAgentToolEventsApi, type CreateAgentToolEventsOptions, type CreateAgentToolEventsResult, type CreateInfiniteQueryOptions, type CreateInfiniteQueryResult, type CreatePaginatedQueryOptions, type CreatePaginatedQueryResult, type CreatePresenceOptions, type CreatePresenceResult, type CreateQueryOptions, type CreateRateLimitOptions, type CreateRateLimitResult, type CreateStreamOptions, type CreateStreamResult, type CreateStreamStatus, type CreateSubscriptionResult, type CreateVoiceAgentOptions, type CreateVoiceAgentResult, type FlagContext, type FlagValue, type HeartbeatReference, type ListPresentReference, LunoraContext, LunoraProvider, type LunoraProviderProps, type MutationClient, type MutationHandle, type MutatorHook, type PageItemOf, type PaginatedArgs, Unauthenticated, type UseAuthResult, type VoiceAudioFormat, type VoiceReference, type VoiceStatus, createAgent, createAgentChat, createAgentState, createAgentToolEvents, createAuth, createConnectionStatus, createFlag, createFlags, createInfiniteQuery, createMutation, createMutationForClient, createMutator, createPaginatedQuery, createPresence, createQuery, createRateLimit, createStream, createSubscription, createVoiceAgent, hydratePreloaded, useLunora };
+type LunoraProviderProps, type MutationClient, type MutationHandle, type MutatorHook, type PageItemOf, type PaginatedArgs, type SolidChildren, Unauthenticated, type UseAuthResult, type VoiceAudioFormat, type VoiceReference, type VoiceStatus, createAction, createActionForClient, createAgent, createAgentChat, createAgentState, createAgentToolEvents, createAuth, createConnectionStatus, createFlag, createFlags, createInfiniteQuery, createLiveTopic, createMutation, createMutationForClient, createMutator, createPaginatedQuery, createPresence, createQuery, createRateLimit, createStream, createSubscription, createVoiceAgent, hydratePreloaded, useLunora };