@memberjunction/graphql-dataprovider 6.2.0-edge.1 → 6.2.0-edge.3

package/dist/index.d.mts

@@ -1,9 +1,10 @@
 import { GraphQLClient } from 'graphql-request';
 export { gql } from 'graphql-request';
-import { ProviderBase, IEntityDataProvider, IMetadataProvider, ProviderConfigDataBase, QueryExecutionSpec, UserInfo, RunQueryResult, RunQueryParams, RunQueryEnrichment, RunQueryWithCacheCheckParams, RunQueriesWithCacheCheckResponse, RunViewParams, RunViewResult, RunViewWithCacheCheckParams, RunViewsWithCacheCheckResponse, EntityInfo, ProviderType, CompositeKey, RecordChange, RecordDependency, KeyValuePair, PotentialDuplicateRequest, PotentialDuplicateResponse, SearchEntityParams, EntitySearchResult, ScoredCandidate, RemoteOpInvokeOptions, RemoteOpResult, RecordMergeRequest, EntityMergeOptions, RecordMergeResult, BaseEntity, EntitySaveOptions, EntityDeleteOptions, DatasetItemFilterType, DatasetResultType, DatasetStatusResultType, TransactionGroupBase, EntityRecordNameInput, EntityRecordNameResult, ILocalStorageProvider, TransactionResult, PlatformSQL } from '@memberjunction/core';
+import { ProviderConfigDataBase, ProviderBase, IEntityDataProvider, IMetadataProvider, QueryExecutionSpec, UserInfo, RunQueryResult, RunQueryParams, RunQueryEnrichment, RunQueryWithCacheCheckParams, RunQueriesWithCacheCheckResponse, RunViewParams, RunViewResult, RunViewWithCacheCheckParams, RunViewsWithCacheCheckResponse, EntityInfo, ProviderType, CompositeKey, RecordChange, RecordDependency, KeyValuePair, PotentialDuplicateRequest, PotentialDuplicateResponse, SearchEntityParams, EntitySearchResult, ScoredCandidate, RemoteOpInvokeOptions, RemoteOpResult, RecordMergeRequest, EntityMergeOptions, RecordMergeResult, BaseEntity, EntitySaveOptions, EntityDeleteOptions, DatasetItemFilterType, DatasetResultType, DatasetStatusResultType, TransactionGroupBase, EntityRecordNameInput, EntityRecordNameResult, ILocalStorageProvider, TransactionResult, PlatformSQL } from '@memberjunction/core';
 import { MJUserViewEntityExtended } from '@memberjunction/core-entities';
 import { Observable } from 'rxjs';
 import { ExecuteAgentParams, ExecuteAgentResult } from '@memberjunction/ai-core-plus';
+import { DecisionQuestion, DecisionAnswer } from '@memberjunction/ai';
 import { ActionParam, ActionResult, EntityActionInvocationParams, EntityActionResult } from '@memberjunction/actions-base';
 import { ListSource, ListRefreshMode, ListDelta, ApplyResult, MaterializeOptions, SetOpKind, ShareTarget, SharePermissionLevel, ShareResult, InviteResult, AcceptInvitationResult, ListShareSummary, SharedListSummary } from '@memberjunction/lists-base';
 import { ComponentSpec } from '@memberjunction/interactive-component-types';
@@ -95,6 +96,60 @@ declare class GraphQLAIClient {
      * @private
      */
     private handlePromptError;
+    /**
+     * Run a typed decision (Likelihood, Choice, Score) on the server in one round trip.
+     *
+     * This calls the `RunDecision` mutation, the fast path for browser features with a tight latency
+     * budget such as routing a message or checking for a duplicate: it carries none of the
+     * `Run Decision` action's execution overhead. The questions and the state are serialized for the
+     * wire and the answers parsed back.
+     *
+     * The method never throws. A failure on the server or in transport is `Success: false` with an
+     * `ErrorMessage` and empty `Answers`.
+     *
+     * @param params The questions, the state, and optionally the prompt and a timeout
+     * @returns A Promise that resolves to the answers by question key, or the reason there are none
+     *
+     * @example
+     * ```typescript
+     * const result = await aiClient.RunDecision({
+     *   State: { message: "Show me last quarter's renewals" },
+     *   Questions: {
+     *     route: {
+     *       Kind: 'Choice',
+     *       Instructions: 'Which agent should answer this message?',
+     *       Options: [
+     *         { Value: 'sage', Description: 'General questions about the product' },
+     *         { Value: 'analyst', Description: 'Questions about data and reports' }
+     *       ]
+     *     }
+     *   },
+     *   TimeoutMS: 250
+     * });
+     *
+     * const route = result.Answers.route;
+     * if (result.Success && route?.Kind === 'Choice') {
+     *   console.log(`Route to ${route.Value} (confidence ${route.Confidence})`);
+     * }
+     * ```
+     */
+    RunDecision(params: RunDecisionParams): Promise<RunDecisionResult>;
+    /**
+     * Prepares the variables for the decision mutation: the questions as JSON, and the state as-is
+     * when it is text or as JSON when it is an object.
+     */
+    private prepareDecisionVariables;
+    /**
+     * Maps the decision mutation's result. The answers are returned only on success, so a caller
+     * never acts on partial ones; answers that cannot be read turn the result into a failure.
+     */
+    private processDecisionResult;
+    /** Parses the answers the server sent, or returns why they cannot be used. */
+    private parseDecisionAnswers;
+    /** Whether a parsed value has the shape of a Likelihood, Choice or Score answer. */
+    private isDecisionAnswer;
+    /** Maps a transport or parsing error to a failed decision result. */
+    private handleDecisionError;
     /**
      * Run an AI agent with the specified parameters.
      *
@@ -207,6 +262,22 @@ declare class GraphQLAIClient {
      * Used by RunAIAgentFromConversationDetail which correlates by conversationDetailId.
      */
     private isConversationDetailCompletionEvent;
+    /**
+     * Does this PubSub message belong to the operation watching `conversationDetailId`?
+     *
+     * FAILS OPEN by design (see `FireAndForgetConfig.isRelevantMessage`): a message carrying no
+     * operation identifier at all — a server-wide notice, a shape we do not recognise — counts as
+     * activity, preserving the pre-#4222 behaviour. Only a message that positively identifies a
+     * DIFFERENT conversation detail or a different agent run is ignored.
+     */
+    private isMessageForConversationDetail;
+    /**
+     * Does this PubSub message belong to the agent run tracked by `ref`?
+     *
+     * Before any run id has been observed the operation has no identity to compare against, so
+     * everything counts (fail open). Once known, a message naming a different run is ignored.
+     */
+    private isMessageForAgentRun;
     /**
      * Capture the agent run id from any PubSub message so the reconciliation hook has a
      * handle even before progress flows. Used only by the plain RunAIAgent path, which
@@ -369,6 +440,43 @@ declare class GraphQLAIClient {
      * @returns A Promise that resolves to a FetchEntityVectorsResult
      */
     FetchEntityVectors(params: FetchEntityVectorsParams): Promise<FetchEntityVectorsResult>;
+    /**
+     * Check the values a person is entering for a new record against the entity's existing records,
+     * and get back the ones to flag as possible duplicates.
+     *
+     * This calls the `CheckDuplicateEntry` mutation. The server finds vector candidates for the
+     * values, keeps those the current user can read, and asks a typed decision about them. It only
+     * flags: nothing is saved, merged or blocked. An entity whose documents do not turn the check on
+     * answers `NotConfigured`; a caller who may not run the check answers `NotAuthorized`.
+     *
+     * The method never throws. A failure on the server or in transport is `Status: 'Failed'` with an
+     * `ErrorMessage` and no candidates. It sets no timeout of its own: a caller with a latency budget
+     * abandons the promise when the budget runs out. The server bounds each check with its own
+     * budget, a little above the form's, so it stops working on an abandoned check soon after.
+     *
+     * @param params The entity and the values entered so far
+     * @returns The flagged candidates, most probable first, or why there are none
+     *
+     * @example
+     * ```typescript
+     * const result = await aiClient.CheckDuplicateEntry({
+     *   EntityName: 'Accounts',
+     *   Values: { Name: 'Acme', City: 'Boston' }
+     * });
+     * if (result.Status === 'Checked') {
+     *   result.Candidates.forEach(c => console.log(`${c.DisplayName} (${c.Probability})`));
+     * }
+     * ```
+     */
+    CheckDuplicateEntry(params: DuplicateEntryCheckParams): Promise<DuplicateEntryCheckResult>;
+    /**
+     * Maps the entry-check mutation's result. A status the client does not know is a failure, so a
+     * caller never acts on a result it cannot read.
+     */
+    private processDuplicateEntryCheckResult;
+    private isDuplicateEntryCheckStatus;
+    /** Maps a transport or parsing error to a failed entry-check result. */
+    private handleDuplicateEntryCheckError;
 }
 /** Result from RunAutotagPipeline */
 interface AutotagPipelineResult {
@@ -445,6 +553,72 @@ interface FetchEntityVectorsResult {
     ElapsedMs: number;
     ErrorMessage?: string;
 }
+/**
+ * Parameters for {@link GraphQLAIClient.CheckDuplicateEntry}
+ */
+interface DuplicateEntryCheckParams {
+    /**
+     * The entity the new record belongs to
+     */
+    EntityName: string;
+    /**
+     * The values entered so far, by field name (sent as JSON). The server ignores fields the entity
+     * does not have.
+     */
+    Values: Record<string, unknown>;
+}
+/**
+ * How an entry-time duplicate check ended.
+ * - `Checked`: the check ran; `Candidates` holds the flagged records, and may be empty.
+ * - `NotConfigured`: the entity's documents do not turn the check on. Nothing else ran.
+ * - `NotAuthorized`: the caller may not run the check (an API key without the scopes, or a user who
+ *   cannot read the entity). Nothing else ran; `ErrorMessage` says why.
+ * - `Failed`: the check could not finish; `ErrorMessage` says why, and nothing is flagged.
+ */
+type DuplicateEntryCheckStatus = 'Checked' | 'NotConfigured' | 'NotAuthorized' | 'Failed';
+/**
+ * An existing record flagged as a possible duplicate of the values being entered
+ */
+interface DuplicateEntryCandidate {
+    /**
+     * The candidate's primary key as a compact URL segment. `CompositeKey.FromURLSegment` reads it back.
+     */
+    RecordID: string;
+    /**
+     * The candidate's name, or its key when the current user may not read a name
+     */
+    DisplayName: string;
+    /**
+     * The vector similarity score that surfaced the candidate
+     */
+    VectorScore: number;
+    /**
+     * The decision's probability that the candidate is the same real-world entity, or null when it
+     * gave no answer for it
+     */
+    Probability: number | null;
+}
+/**
+ * Result from {@link GraphQLAIClient.CheckDuplicateEntry}
+ */
+interface DuplicateEntryCheckResult {
+    /**
+     * How the check ended
+     */
+    Status: DuplicateEntryCheckStatus;
+    /**
+     * Why the check failed, when `Status` is `Failed`
+     */
+    ErrorMessage?: string;
+    /**
+     * The flagged candidates, most probable first. Empty unless `Status` is `Checked`.
+     */
+    Candidates: DuplicateEntryCandidate[];
+    /**
+     * How long the check took on the server, in milliseconds, when the server answered
+     */
+    ElapsedMs?: number;
+}
 /**
  * Parameters for executing a simple prompt
  */
@@ -673,6 +847,72 @@ interface RunAIPromptResult {
      */
     chatResult?: any;
 }
+/**
+ * Parameters for {@link GraphQLAIClient.RunDecision}
+ */
+interface RunDecisionParams {
+    /**
+     * The questions, keyed by a short label for code, answered together in one call.
+     * Write the instructions and option descriptions for the model: it never reads the keys.
+     */
+    Questions: Record<string, DecisionQuestion>;
+    /**
+     * The state the questions are about: text, or an object (sent as JSON).
+     * Keep it to what the questions need.
+     */
+    State: string | Record<string, unknown>;
+    /**
+     * The ID of the Decision-typed prompt to run. Takes precedence over `PromptName`.
+     */
+    PromptID?: string;
+    /**
+     * The name of the Decision-typed prompt to run, matched case-insensitively.
+     * The server uses `Default Decision` when neither this nor `PromptID` is set.
+     */
+    PromptName?: string;
+    /**
+     * Bounds each model call on the server, in milliseconds. Unset or not positive, the server uses
+     * its default, `RunDecisionResolver.DEFAULT_TIMEOUT_MS`; a value over
+     * `RunDecisionResolver.MAX_TIMEOUT_MS` is cut to it. A call is never unbounded.
+     */
+    TimeoutMS?: number;
+}
+/**
+ * Result from {@link GraphQLAIClient.RunDecision}
+ */
+interface RunDecisionResult {
+    /**
+     * Whether the decision ran and its answers were read
+     */
+    Success: boolean;
+    /**
+     * Why the decision failed, when `Success` is false
+     */
+    ErrorMessage?: string;
+    /**
+     * The answers by question key. Empty on failure, so a caller never acts on partial answers.
+     */
+    Answers: Record<string, DecisionAnswer>;
+    /**
+     * ID of the `MJ: AI Prompt Runs` record the server wrote, when the run got that far
+     */
+    PromptRunID?: string;
+    /**
+     * The model that answered, or the one selected when the call failed
+     */
+    ModelName?: string;
+    /**
+     * The exact model behind `ModelName`, as its driver reports it: the vendor's dated model for a
+     * vendor decision model (`typesafe/jev-1.13-20260917`), the chat model for LLM Decision
+     * (`GPT-OSS-120B`). A calibration fitted on one model applies only to that model's answers, so a
+     * consumer that calibrates needs both names. Absent when the driver reports none.
+     */
+    ResolvedModel?: string;
+    /**
+     * Server-side execution time in milliseconds
+     */
+    ExecutionTimeMs?: number;
+}
 /**
  * Parameters for running an AI agent from an existing conversation detail.
  * This is the optimized method that loads conversation history server-side.
@@ -987,6 +1227,27 @@ declare class GraphQLDataProvider extends ProviderBase implements IEntityDataPro
      * @returns
      */
     Config(configData: GraphQLProviderConfigData, providerToUse?: IMetadataProvider, separateConnection?: boolean, forceRefreshSessionId?: boolean): Promise<boolean>;
+    /**
+     * The authenticate-only half of {@link Config}, for embedded/anonymous surfaces that only make
+     * their own GraphQL calls. After it resolves, {@link ExecuteGQL} works. No metadata is fetched,
+     * so entity metadata (`Entities`, `EntityByName`, `RunView`, `GetEntityObject`) is NOT available
+     * until the full boot runs (`SetupGraphQLClient`, or {@link Config}) on this same instance.
+     * Uses the shared singleton connection (a secondary instance keeps its own). A later Connect/Config with a different URL,
+     * token or API key rebuilds that connection's client (keeping the session id).
+     */
+    Connect(configData: GraphQLProviderConfigData): Promise<void>;
+    /**
+     * The connection half of {@link Config}: stores the config, resolves the session id and creates the
+     * GraphQL client (this instance's own client when separateConnection is true or this is not the
+     * global singleton, otherwise the shared singleton client, which is reused unless the credentials
+     * changed). Loads no metadata.
+     */
+    private connectClient;
+    /**
+     * True when `client` was built with a URL or credentials other than `configData`'s. A client this
+     * class did not record (a subclass's own CreateNewGraphQLClient, a test harness) is kept as-is.
+     */
+    private isBuiltWithOtherCredentials;
     get sessionId(): string;
     protected get AllowRefresh(): boolean;
     /**
@@ -1203,6 +1464,17 @@ declare class GraphQLDataProvider extends ProviderBase implements IEntityDataPro
     CreateTransactionGroup(): Promise<TransactionGroupBase>;
     GetRecordFavoriteStatus(userId: string, entityName: string, primaryKey: CompositeKey): Promise<boolean>;
     SetRecordFavoriteStatus(userId: string, entityName: string, primaryKey: CompositeKey, isFavorite: boolean, contextUser: UserInfo): Promise<void>;
+    /**
+     * Record names this connection has seen, for synchronous display code. Safe to keep here
+     * because every request on a connection is answered as the same user.
+     */
+    private readonly _recordNames;
+    GetCachedRecordName(entityName: string, compositeKey: CompositeKey, loadIfNeeded?: boolean): Promise<string | undefined>;
+    HasCachedRecordName(entityName: string, compositeKey: CompositeKey): boolean;
+    GetCachedRecordNameOnlyIfCached(entityName: string, compositeKey: CompositeKey): string | undefined;
+    SetCachedRecordName(entityName: string, compositeKey: CompositeKey, recordName: string): void;
+    GetEntityRecordName(entityName: string, compositeKey: CompositeKey, contextUser?: UserInfo, forceRefresh?: boolean): Promise<string>;
+    GetEntityRecordNames(info: EntityRecordNameInput[], contextUser?: UserInfo, forceRefresh?: boolean): Promise<EntityRecordNameResult[]>;
     protected InternalGetEntityRecordName(entityName: string, primaryKey: CompositeKey): Promise<string>;
     protected InternalGetEntityRecordNames(info: EntityRecordNameInput[]): Promise<EntityRecordNameResult[]>;
     /**
@@ -1290,7 +1562,16 @@ declare class GraphQLDataProvider extends ProviderBase implements IEntityDataPro
     private _wsClient;
     private _wsClientCreatedAt;
     private _socketStateSubject;
+    private _socketReconnectedSubject;
     private _isDisposingSocketIntentionally;
+    /** Disarms the current client's pong watchdog. Each client owns its own timer. */
+    private _disarmPongWatchdog;
+    /**
+     * Fires each time the socket comes back up after having dropped — never on the first
+     * connect. Subscribers should treat it as "you may have missed events while you were
+     * away; re-read authoritative state", because the push topic has no replay buffer.
+     */
+    get SocketReconnected$(): Observable<void>;
     /**
      * Observable of the WebSocket (graphql-ws) connection state. Used by
      * connectivity monitors as the primary signal for server reachability,
@@ -1301,6 +1582,11 @@ declare class GraphQLDataProvider extends ProviderBase implements IEntityDataPro
      * Current WebSocket connection state (synchronous snapshot).
      */
     get SocketConnectionState(): SocketConnectionState;
+    /**
+     * How many WebSocket subscriptions are currently open. Zero means nothing is waiting on
+     * push frames, so a socket that is down is delivering nothing and costing nothing.
+     */
+    get ActiveSubscriptionCount(): number;
     /**
      * Force-dispose the current WebSocket client so the next subscription
      * creates a fresh connection. Called by ServerConnectivityService after
@@ -1496,10 +1782,24 @@ declare class GraphQLDataProvider extends ProviderBase implements IEntityDataPro
  * Setup the GraphQL client for the project using the provided configuration data.
  */
 declare function SetupGraphQLClient(config: GraphQLProviderConfigData): Promise<GraphQLDataProvider>;
+/**
+ * Connects and registers the GraphQL provider WITHOUT booting metadata. For anonymous/embedded
+ * surfaces that only make their own GraphQL calls (and MJ's realtime runtime): no metadata
+ * download, no current-user fetch, no LoggedIn event, no startup engines. Call
+ * {@link SetupGraphQLClient} later to finish the full boot on the same instance.
+ *
+ * If the global provider already has metadata loaded this is a no-op that returns it, so it can
+ * never downgrade a fully booted provider. Called again on a connected but unbooted provider, it
+ * replaces `ConfigData` and keeps the session id; when the URL, token or API keys differ from the
+ * ones the current client was built with, it rebuilds the client so requests carry the new
+ * identity. The same applies when {@link SetupGraphQLClient} later runs with a login's config
+ * (an anonymous connect upgraded to a signed-in user).
+ */
+declare function ConnectGraphQLClient(config: GraphQLProviderConfigData): Promise<GraphQLDataProvider>;
 /** @deprecated Use {@link SetupGraphQLClient}. */
 declare function setupGraphQLClient(config: GraphQLProviderConfigData): Promise<GraphQLDataProvider>;
 
-declare const PACKAGE_VERSION = "6.2.0-edge.1";
+declare const PACKAGE_VERSION = "6.2.0-edge.3";
 
 declare class GraphQLTransactionGroup extends TransactionGroupBase {
     private _provider;
@@ -2822,6 +3122,11 @@ interface RunViewSystemUserInput {
      * Starting row number for pagination (optional, 0-based)
      */
     StartRow?: number;
+    /**
+     * When true, binary fields (varbinary / bytea columns) are returned as base64 strings.
+     * They are omitted by default; a binary field named in `Fields` is always returned. (optional)
+     */
+    IncludeBinaryFields?: boolean;
 }
 /**
  * Result row type for view execution results - represents a single data row
@@ -4030,6 +4335,16 @@ interface StartLiveKitAgentRoomSessionInput {
     AgentSessionID?: string;
     /** Turn-taking mode. */
     TurnMode?: 'Passive' | 'Active' | 'Hybrid';
+    /**
+     * Start the agent able to bring someone into this room (a person who is offered the conversation, a phone number, or another
+     * agent). Opt-in; honoured only when the server is configured for handoffs, otherwise the agent starts as usual.
+     */
+    EnableHandoff?: boolean;
+    /**
+     * How the agent decides it was addressed: `Auto` (default — the model's own judgement when it is full-duplex,
+     * name matching otherwise), `ModelSide`, or `Regex`.
+     */
+    TurnAddressing?: 'Auto' | 'ModelSide' | 'Regex';
 }
 /** Result of starting an agent room session (includes a client token so the caller can immediately join). */
 interface LiveKitAgentRoomSessionResult {
@@ -4081,6 +4396,76 @@ interface LiveKitRecordingResult {
      */
     RecordingFileID?: string;
 }
+/** The kinds of events a room's turn-taking log records. */
+type LiveKitTurnEventType = 'FloorGranted' | 'FloorReleased' | 'FloorDenied' | 'Yielded' | 'Backchannel' | 'HumanSpeech' | 'HumanPreempted' | 'LoopCapReached';
+/** One recorded turn-taking event. */
+interface LiveKitRoomTurnEvent {
+    /** Monotonic per-room sequence number — poll with the last `Seq` seen to render only what is new. */
+    Seq: number;
+    /** Epoch-ms the event happened (server clock). */
+    AtMs: number;
+    /** What happened. */
+    Type: LiveKitTurnEventType;
+    /** The agent session the event is about, when it concerns one. */
+    AgentSessionId?: string;
+    /** For `Yielded`: the agent the floor was handed to. */
+    ToAgentSessionId?: string;
+    /** A short machine-readable reason (e.g. `HeldByOtherAgent`, `HumanSpeaking`, `LoopCapReached`). */
+    Reason?: string;
+}
+/** One agent seated in a room, as the turn-taking state describes it. */
+interface LiveKitRoomTurnAgent {
+    /** The agent's `MJ: AI Agent Sessions` id (matches the ids in {@link LiveKitRoomTurnState}). */
+    AgentSessionID: string;
+    /** The bridge row id (what {@link GraphQLLiveKitClient.StopAgentRoomSession} removes it by). */
+    SessionBridgeID: string;
+    /** The names the agent answers to; the first is its display name. */
+    Names: string[];
+    /** The configured turn-taking mode. */
+    TurnMode: 'Passive' | 'Active' | 'Hybrid';
+    /** How it decides it was addressed (after the model's capability was taken into account). */
+    Addressing: 'ModelSide' | 'Regex';
+    /** Whether its model is full-duplex (its speech runs through the floor gate). */
+    FullDuplex: boolean;
+}
+/** A room's live turn-taking state. */
+interface LiveKitRoomTurnState {
+    /** The room. */
+    RoomId: string;
+    /** The agent session ids seated in the room. */
+    AgentSessionIds: string[];
+    /** The facilitator's agent session id, or `null`. */
+    FacilitatorAgentSessionId: string | null;
+    /** The agent session holding the floor, or `null` when it is free. */
+    FloorHolderAgentSessionId: string | null;
+    /** Epoch-ms the holder took the floor, or `null`. */
+    FloorHeldSinceMs: number | null;
+    /** Whether a person is speaking right now. */
+    HumanSpeaking: boolean;
+    /** The agent session the floor is reserved for after a hand-off, or `null`. */
+    PendingHandoffToAgentSessionId: string | null;
+    /** Consecutive agent turns since a person last spoke. */
+    ConsecutiveAgentTurns: number;
+    /** The cap on consecutive agent turns for this room. */
+    MaxConsecutiveAgentTurns: number;
+    /** Whether the loop cap is reached — agents are passive until a person speaks. */
+    LoopCapReached: boolean;
+    /** How many backchannels the room has recorded. */
+    BackchannelCount: number;
+    /** The most recent events, oldest first. */
+    RecentEvents: LiveKitRoomTurnEvent[];
+    /** The agents seated in the room. */
+    Agents: LiveKitRoomTurnAgent[];
+}
+/** Result of {@link GraphQLLiveKitClient.GetRoomTurnState}. */
+interface LiveKitRoomTurnStateResult {
+    /** Whether the query succeeded. */
+    Success: boolean;
+    /** Error detail when {@link Success} is false. */
+    ErrorMessage?: string;
+    /** The room's turn-taking state, or `null` when the room holds no agents. */
+    State: LiveKitRoomTurnState | null;
+}
 /** Typed wrapper over the LiveKit room GraphQL mutations. */
 declare class GraphQLLiveKitClient {
     private _dataProvider;
@@ -4123,6 +4508,14 @@ declare class GraphQLLiveKitClient {
      * @returns `true` when at least one invite was delivered.
      */
     InviteUsers(roomName: string, userIDs: string[]): Promise<boolean>;
+    /**
+     * Reads a room's live turn-taking state — who holds the floor, whether a person is speaking, any pending
+     * hand-off, the agent-to-agent loop-cap progress, the most recent floor events, and who is seated. Poll it
+     * (about once a second) to drive a turn-taking display. Never throws; a failure resolves `{ Success: false }`.
+     *
+     * @param roomName The LiveKit room.
+     */
+    GetRoomTurnState(roomName: string): Promise<LiveKitRoomTurnStateResult>;
     /**
      * Fetches active Realtime models with each driver's supported voices — populates the dev model/voice
      * picker. Best-effort: any failure resolves to `[]` so the picker simply offers no overrides.
@@ -4149,6 +4542,96 @@ declare class GraphQLLiveKitClient {
     private runRecordingMutation;
 }
 
+/**
+ * Typed client for the **human handoff** GraphQL surface (MJServer `HumanHandoffResolver`): the person-at-a-console side of a
+ * room handoff. An AI agent in a LiveKit room (a phone call that arrived through SIP, or a web room) can ask for a person to
+ * take the conversation over; that person is OFFERED it and may accept or decline. Every call is scoped to the signed-in
+ * user server-side, so a user lists, accepts and declines only their own offers.
+ *
+ * Accepting returns the room to join; the console then joins it through the same LiveKit token path the Meet room uses
+ * (`GraphQLLiveKitClient.MintClientToken`), and the AI leaves once the person is in the room.
+ *
+ * @example
+ * ```typescript
+ * const handoff = new GraphQLHandoffClient(GraphQLDataProvider.Instance);
+ * const offers = await handoff.GetMyOffers();
+ * handoff.ObserveOfferChanges().subscribe((change) => refresh(change));
+ * const accepted = await handoff.AcceptOffer(offers[0].OfferID);
+ * if (accepted.Success) { joinRoom(accepted.RoomName); }
+ * ```
+ */
+/** Where an offer stands. */
+type HandoffOfferStatus = 'Pending' | 'Accepted' | 'Declined' | 'Expired' | 'Cancelled';
+/** One conversation offered to the signed-in user. */
+interface HandoffOfferInfo {
+    OfferID: string;
+    RoomName: string;
+    /** `warm` (the AI introduces you, then leaves) or `blind` (the AI leaves as soon as you join). */
+    Mode: string;
+    /** The AI's summary of the conversation so far. */
+    Summary: string;
+    /** Who is on the other end (a masked number, "Web visitor"). */
+    CallerLabel: string;
+    /** The AI agent that is in the room. */
+    AgentName: string;
+    Status: HandoffOfferStatus;
+    /** ISO-8601 UTC. */
+    CreatedAt: string;
+    /** ISO-8601 UTC; after this the offer can no longer be accepted. */
+    ExpiresAt: string;
+    /** The MJ interaction ID associated with this conversation/room, if known. */
+    InteractionID?: string | null;
+}
+/** One change to an offer, pushed live. */
+interface HandoffOfferChange {
+    /** `offered` for a new offer; `updated` when it was accepted, declined, expired or cancelled. */
+    Kind: 'offered' | 'updated';
+    Offer: HandoffOfferInfo;
+}
+/** Result of accepting an offer. */
+interface AcceptHandoffOfferResult {
+    Success: boolean;
+    ErrorMessage?: string;
+    /** The room to join. Empty on failure. */
+    RoomName: string;
+    Offer?: HandoffOfferInfo;
+}
+/** Result of declining an offer. */
+interface DeclineHandoffOfferResult {
+    Success: boolean;
+    ErrorMessage?: string;
+}
+declare class GraphQLHandoffClient {
+    private readonly _dataProvider;
+    /**
+     * @param dataProvider The GraphQL data provider that carries the requests (it holds the signed-in session).
+     */
+    constructor(dataProvider: GraphQLDataProvider);
+    /**
+     * The signed-in user's offers: pending ones, plus ones that resolved recently enough to still be shown. Best-effort: a
+     * transport failure is logged and resolves to an empty list so the console shows "nothing waiting" rather than throwing.
+     */
+    GetMyOffers(): Promise<HandoffOfferInfo[]>;
+    /**
+     * Accepts an offer. The server authorises it against the offer's target, so another user's offer (or a missing, expired or
+     * cancelled one) answers `Success: false`. Never throws.
+     *
+     * @param offerID The offer to accept.
+     */
+    AcceptOffer(offerID: string): Promise<AcceptHandoffOfferResult>;
+    /**
+     * Declines an offer, so the AI can fall back (the person's phone, or carrying on). Never throws.
+     *
+     * @param offerID The offer to decline.
+     */
+    DeclineOffer(offerID: string): Promise<DeclineHandoffOfferResult>;
+    /**
+     * Live changes to the signed-in user's offers. The server delivers only this user's. The stream completes when the session's
+     * token is refreshed (re-subscribe to continue), as every MJ subscription does.
+     */
+    ObserveOfferChanges(): Observable<HandoffOfferChange>;
+}
+
 /**
  * Input for the `GenerateSeedTaxonomy` GraphQL mutation.
  *
@@ -4472,6 +4955,21 @@ interface FireAndForgetConfig<TResult> {
      * Use this to forward progress updates to UI callbacks.
      */
     onMessage?: (parsed: Record<string, unknown>) => void;
+    /**
+     * Optional predicate deciding whether a PubSub message belongs to THIS operation.
+     *
+     * The push-status subscription is per-SESSION, not per-operation, so without this every
+     * message for every concurrent run resets every pending operation's idle timer. With
+     * several agents in flight, one chatty run holds a dead run's timer open indefinitely —
+     * the "idle" window silently means "the whole session went quiet", which is not what any
+     * caller intends (MJ #4222).
+     *
+     * MUST FAIL OPEN: return `true` for anything not positively identifiable as another
+     * operation's. Wrongly ignoring a message that IS ours shortens the window and causes a
+     * spurious reconcile; wrongly accepting one that is not merely preserves the old
+     * behaviour. When omitted, every message counts as activity, exactly as before.
+     */
+    isRelevantMessage?: (parsed: Record<string, unknown>) => boolean;
     /**
      * Optional reconciliation hook invoked when the idle timer expires (no message
      * received within the idle window) or the PubSub stream drops. Should query the
@@ -5469,6 +5967,11 @@ declare class BrowserStorageProviderBase implements ILocalStorageProvider {
      * See {@link ILocalStorageProvider.SharesReferences}.
      */
     get SharesReferences(): boolean;
+    /**
+     * `false` — the base tier is a `Map` on the heap, which dies with the page. Subclasses with a
+     * real backend override this. See {@link ILocalStorageProvider.SupportsCrossProcessPersistence}.
+     */
+    get SupportsCrossProcessPersistence(): boolean;
     private _storage;
     /**
      * Gets or creates a category map
@@ -5538,6 +6041,13 @@ declare class BrowserIndexedDBStorageProvider extends BrowserStorageProviderBase
      * the DB is unreachable), so there is no fallback path that could reintroduce sharing.
      */
     get SharesReferences(): boolean;
+    /**
+     * `true` — IndexedDB outlives the page. Unlike the localStorage provider this class never
+     * defers to the in-memory base tier, so there is no fallback that would make a stored
+     * snapshot unreadable on the next load.
+     * See {@link ILocalStorageProvider.SupportsCrossProcessPersistence}.
+     */
+    get SupportsCrossProcessPersistence(): boolean;
     private dbPromise;
     private _dbReady;
     constructor();
@@ -5942,6 +6452,169 @@ declare class GraphQLIntegrationClient {
     private handleError;
 }
 
-export { ActionItemInput, ActionItemOutput, BrowserIndexedDBStorageProvider, BrowserStorageProviderBase, FieldMapper, FireAndForgetHelper, GetDataOutput, GraphQLAIClient, GraphQLActionClient, GraphQLClassifyClient, GraphQLClusterClient, GraphQLComponentRegistryClient, GraphQLDataProvider, GraphQLEncryptionClient, GraphQLFileStorageClient, GraphQLIntegrationClient, GraphQLListsClient, GraphQLLiveKitClient, GraphQLProviderConfigData, GraphQLSearchClient, GraphQLSystemUserClient, GraphQLTestingClient, GraphQLTransactionGroup, GraphQLVersionHistoryClient, PACKAGE_VERSION, RoleInput, RolesAndUsersInput, SafeGraphQLError, SanitizeGraphQLError, SetupGraphQLClient, SimpleRemoteEntity, SimpleRemoteEntityField, SimpleRemoteEntityOutput, SyncDataAction, SyncDataResult, SyncRolesAndUsersResult, ToSafeGraphQLError, UserInput, setupGraphQLClient };
-export type { AccountSearchResult, ApplyAllEntityMapCreated, ApplyAllResult, AuthenticationErrorCallback, AutotagPipelineResult, CheckEntityPermissionsResult, ClusterAnalysisInfo, ClusterAnalysisMetrics, ClusterAnalysisPoint, ComponentDependencyTree, ComponentSpecWithHash, ConnectionTestGraphQLResult, CopyBetweenAccountsResult, CreateAPIKeyParams, CreateAPIKeyResult, CreatePreAuthUploadUrlResult, CreateQueryInput, CreateQueryResult, CreateVersionLabelParams, CreateVersionLabelProgress, CreateVersionLabelResult, DefaultConfigResult, DefaultFieldMappingResult, DefaultObjectConfigResult, DeleteQueryOptionsInput, DeleteQueryResult, DiscoveredFieldResult, DiscoveredObjectResult, DiscoveryResult, EmbedTextParams, EmbedTextResult, EntityPermissionResultItem, ExecuteSimplePromptParams, FileSearchOptions, FileSearchResult, FireAndForgetConfig, GenerateSeedTaxonomyInput, GetQueryDataByNameSystemUserInput, GetQueryDataSystemUserInput, GetRegistryComponentParams, LiveKitAgentRoomSessionResult, LiveKitClientTokenResult, LiveKitRecordingResult, MJMetadataDB, MJQueryEntity, MJ_MetadataDB, MintLiveKitClientTokenInput, PreviewDataResult, PreviewRecordResult, PreviewSearchSystemUserInput, QueryDependencySpecClientInput, QueryField, QueryMutationQueryData, QueryMutationResult, QueryParameter, QueryParameterHintInput, QueryPermission, QueryPermissionInput, RealtimeModelVoices, RealtimeVoiceOption, RegistryComponentSearchResult, RevokeAPIKeyResult, RunAIAgentFromConversationDetailParams, RunAIPromptParams, RunAIPromptResult, RunClusterAnalysisInput, RunClusterAnalysisResult, RunDynamicViewSystemUserInput, RunQuerySystemUserResult, RunTestParams, RunTestResult, RunTestSuiteParams, RunTestSuiteResult, RunViewByIDSystemUserInput, RunViewByNameSystemUserInput, RunViewSystemUserInput, RunViewSystemUserResult, RunViewSystemUserResultRow, SanitizedGraphQLError, SanitizedGraphQLErrorDetail, SchemaPreviewFile, SchemaPreviewObjectInput, SchemaPreviewResult, SearchAcrossAccountsResult, SearchClientFilters, SearchClientParams, SearchClientProviderInfo, SearchClientResponse, SearchClientResultItem, SearchKnowledgeSystemUserInput, SearchRegistryComponentsParams, SearchScoreBreakdown, SearchSourceCounts, SeedTaxonomyNode, SeedTaxonomyResult, SimplePromptResult, SocketConnectionState, SourceObjectListItem, SourceObjectSelectionInput, StartLiveKitAgentRoomSessionInput, StorageListResult, StorageObjectMetadata, TaskGraphFrameEvent, TestExecutionProgress, TestQuerySQLClientInput, TestQuerySQLClientResult, UpdateQueryInput, UpdateQueryResult, UploadFileInput, UploadFileResult, VariableShape, VectorizeEntityParams, VectorizeEntityResult };
+/** One persisted step of an agent run, as returned by the durable tail query. */
+interface ConversationRunEvent {
+    /** Monotonic position within the run — the cursor value to page from. */
+    Seq: number;
+    StepType: string;
+    StepName: string;
+    Status: string;
+    Success?: boolean;
+    ErrorMessage?: string;
+    StartedAt: string;
+    CompletedAt?: string;
+}
+/** Result of one tail call. */
+interface ConversationTailResult {
+    Success: boolean;
+    Message: string;
+    Events: ConversationRunEvent[];
+    /** Cursor to pass as `sinceSeq` next time. Never rewinds. */
+    LatestSeq: number;
+    /** True while the run is still executing. False means terminal — stop tailing. */
+    IsInFlight: boolean;
+    RunID?: string;
+    RunStatus?: string;
+    /** The run's persisted result, populated only once the run is terminal. */
+    FinalPayload?: string;
+    /** `ConversationDetail.Status` — what the chat UI renders from. */
+    DetailStatus?: string;
+}
+/**
+ * Client for the durable, resumable read of a conversation's agent-run progress (MJ #4222).
+ *
+ * The `statusUpdates` subscription is the only live path a conversation has and it has no replay:
+ * the server topic is an in-memory PubSub and the client subject is unbuffered. Anything published
+ * while the socket was half-open is gone, and the client cannot tell "nothing happened" from
+ * "I missed everything". This query is the durable counterpart — a client keeps the `LatestSeq`
+ * it has seen and re-reads from there after any interruption.
+ *
+ * Runs over plain HTTP, so it works while the WebSocket is still dead. That is the property the
+ * whole recovery path depends on.
+ */
+declare class GraphQLConversationClient {
+    private _dataProvider;
+    constructor(dataProvider: GraphQLDataProvider);
+    /**
+     * Read agent-run events for a conversation detail from a cursor forward.
+     *
+     * @param conversationDetailID The message to tail.
+     * @param sinceSeq Highest `Seq` already seen; 0 or omitted reads from the start.
+     * @returns Never throws — a transport failure comes back as `Success: false` with the caller's
+     *     cursor preserved, because this IS the recovery path and throwing from it would break the
+     *     reconciliation it exists to serve.
+     */
+    TailConversationEvents(conversationDetailID: string, sinceSeq?: number): Promise<ConversationTailResult>;
+    private failure;
+}
+
+interface MeetingParticipantInfo {
+    ID: string;
+    MeetingID: string;
+    UserID?: string;
+    UserName?: string;
+    UserEmail?: string;
+    AgentID?: string;
+    AgentName?: string;
+    ExternalName?: string;
+    ExternalEmail?: string;
+    ExternalPhone?: string;
+    Role: 'Host' | 'CoHost' | 'Attendee' | 'Agent';
+    InviteStatus: 'Accepted' | 'Declined' | 'Invited' | 'Tentative';
+    JoinedAt?: string;
+    LeftAt?: string;
+}
+interface MeetingInfo {
+    ID: string;
+    Title: string;
+    Description?: string;
+    HostUserID: string;
+    HostUserName?: string;
+    RoomName: string;
+    Status: 'Scheduled' | 'Live' | 'Ended' | 'Cancelled';
+    ScheduledStartAt?: string;
+    ScheduledEndAt?: string;
+    StartedAt?: string;
+    EndedAt?: string;
+    AllowPhoneDialIn: boolean;
+    DialInPhoneNumberID?: string;
+    DialInPhoneNumber?: string;
+    DialInCode?: string;
+    RecordingPolicy: 'Off' | 'Allowed' | 'Automatic';
+    ConversationID?: string;
+    Participants?: MeetingParticipantInfo[];
+    CreatedAt: string;
+    UpdatedAt: string;
+}
+interface DialInPhoneNumberInfo {
+    ID: string;
+    Number: string;
+    Label?: string;
+}
+interface MeetingParticipantInput {
+    UserID?: string;
+    AgentID?: string;
+    ExternalName?: string;
+    ExternalEmail?: string;
+    ExternalPhone?: string;
+    Role?: string;
+}
+interface CreateMeetingInput {
+    Title: string;
+    Description?: string;
+    ScheduledStartAt?: Date;
+    ScheduledEndAt?: Date;
+    AllowPhoneDialIn?: boolean;
+    DialInPhoneNumberID?: string;
+    RecordingPolicy?: string;
+    Participants?: MeetingParticipantInput[];
+}
+interface UpdateMeetingInput {
+    MeetingID: string;
+    Title?: string;
+    Description?: string;
+    ScheduledStartAt?: Date;
+    ScheduledEndAt?: Date;
+    AllowPhoneDialIn?: boolean;
+    DialInPhoneNumberID?: string;
+    RecordingPolicy?: string;
+    Participants?: MeetingParticipantInput[];
+}
+interface RSVPMeetingInput {
+    MeetingID: string;
+    InviteStatus: 'Accepted' | 'Declined' | 'Tentative';
+}
+interface MeetingResult {
+    Success: boolean;
+    ErrorMessage?: string;
+    Meeting?: MeetingInfo;
+}
+interface StartMeetingResult {
+    Success: boolean;
+    ErrorMessage?: string;
+    Meeting?: MeetingInfo;
+    RoomName?: string;
+    ClientToken?: string;
+}
+/**
+ * Typed client for the MemberJunction **Meeting** GraphQL surface (MJServer `MeetingResolver`).
+ */
+declare class GraphQLMeetingClient {
+    private _dataProvider;
+    constructor(dataProvider?: GraphQLDataProvider | IMetadataProvider);
+    GetMeeting(id: string): Promise<MeetingInfo | null>;
+    MyMeetings(status?: string): Promise<MeetingInfo[]>;
+    Meeting(id: string): Promise<MeetingInfo | null>;
+    MeetingParticipants(meetingID: string): Promise<MeetingParticipantInfo[]>;
+    AvailableDialInPhoneNumbers(): Promise<DialInPhoneNumberInfo[]>;
+    CreateMeeting(input: CreateMeetingInput): Promise<MeetingResult>;
+    UpdateMeeting(input: UpdateMeetingInput): Promise<MeetingResult>;
+    StartMeeting(meetingID: string): Promise<StartMeetingResult>;
+    EndMeeting(meetingID: string): Promise<MeetingResult>;
+    CancelMeeting(meetingID: string): Promise<MeetingResult>;
+    RSVPMeeting(input: RSVPMeetingInput): Promise<MeetingResult>;
+}
+
+export { ActionItemInput, ActionItemOutput, BrowserIndexedDBStorageProvider, BrowserStorageProviderBase, ConnectGraphQLClient, FieldMapper, FireAndForgetHelper, GetDataOutput, GraphQLAIClient, GraphQLActionClient, GraphQLClassifyClient, GraphQLClusterClient, GraphQLComponentRegistryClient, GraphQLConversationClient, GraphQLDataProvider, GraphQLEncryptionClient, GraphQLFileStorageClient, GraphQLHandoffClient, GraphQLIntegrationClient, GraphQLListsClient, GraphQLLiveKitClient, GraphQLMeetingClient, GraphQLProviderConfigData, GraphQLSearchClient, GraphQLSystemUserClient, GraphQLTestingClient, GraphQLTransactionGroup, GraphQLVersionHistoryClient, PACKAGE_VERSION, RoleInput, RolesAndUsersInput, SafeGraphQLError, SanitizeGraphQLError, SetupGraphQLClient, SimpleRemoteEntity, SimpleRemoteEntityField, SimpleRemoteEntityOutput, SyncDataAction, SyncDataResult, SyncRolesAndUsersResult, ToSafeGraphQLError, UserInput, setupGraphQLClient };
+export type { AcceptHandoffOfferResult, AccountSearchResult, ApplyAllEntityMapCreated, ApplyAllResult, AuthenticationErrorCallback, AutotagPipelineResult, CheckEntityPermissionsResult, ClusterAnalysisInfo, ClusterAnalysisMetrics, ClusterAnalysisPoint, ComponentDependencyTree, ComponentSpecWithHash, ConnectionTestGraphQLResult, ConversationRunEvent, ConversationTailResult, CopyBetweenAccountsResult, CreateAPIKeyParams, CreateAPIKeyResult, CreateMeetingInput, CreatePreAuthUploadUrlResult, CreateQueryInput, CreateQueryResult, CreateVersionLabelParams, CreateVersionLabelProgress, CreateVersionLabelResult, DeclineHandoffOfferResult, DefaultConfigResult, DefaultFieldMappingResult, DefaultObjectConfigResult, DeleteQueryOptionsInput, DeleteQueryResult, DialInPhoneNumberInfo, DiscoveredFieldResult, DiscoveredObjectResult, DiscoveryResult, DuplicateEntryCandidate, DuplicateEntryCheckParams, DuplicateEntryCheckResult, DuplicateEntryCheckStatus, EmbedTextParams, EmbedTextResult, EntityPermissionResultItem, ExecuteSimplePromptParams, FileSearchOptions, FileSearchResult, FireAndForgetConfig, GenerateSeedTaxonomyInput, GetQueryDataByNameSystemUserInput, GetQueryDataSystemUserInput, GetRegistryComponentParams, HandoffOfferChange, HandoffOfferInfo, HandoffOfferStatus, LiveKitAgentRoomSessionResult, LiveKitClientTokenResult, LiveKitRecordingResult, LiveKitRoomTurnAgent, LiveKitRoomTurnEvent, LiveKitRoomTurnState, LiveKitRoomTurnStateResult, LiveKitTurnEventType, MJMetadataDB, MJQueryEntity, MJ_MetadataDB, MeetingInfo, MeetingParticipantInfo, MeetingParticipantInput, MeetingResult, MintLiveKitClientTokenInput, PreviewDataResult, PreviewRecordResult, PreviewSearchSystemUserInput, QueryDependencySpecClientInput, QueryField, QueryMutationQueryData, QueryMutationResult, QueryParameter, QueryParameterHintInput, QueryPermission, QueryPermissionInput, RSVPMeetingInput, RealtimeModelVoices, RealtimeVoiceOption, RegistryComponentSearchResult, RevokeAPIKeyResult, RunAIAgentFromConversationDetailParams, RunAIPromptParams, RunAIPromptResult, RunClusterAnalysisInput, RunClusterAnalysisResult, RunDecisionParams, RunDecisionResult, RunDynamicViewSystemUserInput, RunQuerySystemUserResult, RunTestParams, RunTestResult, RunTestSuiteParams, RunTestSuiteResult, RunViewByIDSystemUserInput, RunViewByNameSystemUserInput, RunViewSystemUserInput, RunViewSystemUserResult, RunViewSystemUserResultRow, SanitizedGraphQLError, SanitizedGraphQLErrorDetail, SchemaPreviewFile, SchemaPreviewObjectInput, SchemaPreviewResult, SearchAcrossAccountsResult, SearchClientFilters, SearchClientParams, SearchClientProviderInfo, SearchClientResponse, SearchClientResultItem, SearchKnowledgeSystemUserInput, SearchRegistryComponentsParams, SearchScoreBreakdown, SearchSourceCounts, SeedTaxonomyNode, SeedTaxonomyResult, SimplePromptResult, SocketConnectionState, SourceObjectListItem, SourceObjectSelectionInput, StartLiveKitAgentRoomSessionInput, StartMeetingResult, StorageListResult, StorageObjectMetadata, TaskGraphFrameEvent, TestExecutionProgress, TestQuerySQLClientInput, TestQuerySQLClientResult, UpdateMeetingInput, UpdateQueryInput, UpdateQueryResult, UploadFileInput, UploadFileResult, VariableShape, VectorizeEntityParams, VectorizeEntityResult };
 //# sourceMappingURL=index.d.mts.map