@memberjunction/livekit-room-server 6.2.0-edge.1 → 6.2.0-edge.3

package/dist/room-handoff/handoff-offer-registry.d.ts

@@ -0,0 +1,137 @@
+/**
+ * @fileoverview Durable registry of handoff offers backed by `MJ: Interaction Offers`.
+ *
+ * An offer is a short-lived question put to one person: "a caller is waiting, will you take the conversation?".
+ * It lives in `MJ: Interaction Offers` from the moment the AI asks until it is accepted, declined, expired or cancelled,
+ * and is kept so a console that was open when it resolved can still show what happened.
+ *
+ * **Durable and cluster-safe.** Offers are stored in the database (`MJ: Interaction Offers`). Accept and decline
+ * execute a compare-and-set on `Status = 'Pending'` inside `RunInEntityTransaction` so multiple server instances
+ * cannot both accept or race. Expired offers are updated on read and through a periodic sweep. Live changes are
+ * published locally and across instances via cluster pub/sub.
+ *
+ * An accept or decline is authorised by comparing the offer's target user with the caller, and a mismatch answers
+ * exactly as a missing offer does: someone who does not own an offer cannot learn that it exists.
+ *
+ * @module @memberjunction/livekit-room-server
+ */
+import { IMetadataProvider, UserInfo } from '@memberjunction/core';
+import { BaseSingleton } from '@memberjunction/global';
+import type { HandoffMode, HandoffOfferStatus, HandoffOfferView } from './handoff-types.js';
+/** How long a person has to accept an offer before it expires. */
+export declare const HANDOFF_OFFER_TIMEOUT_MS = 45000;
+/** How long a resolved offer stays listed (so a console that was open still sees what happened). */
+export declare const HANDOFF_OFFER_RETENTION_MS: number;
+/** The most pending offers one person can have at once; a flood of offers is refused rather than queued. */
+export declare const MAX_PENDING_OFFERS_PER_USER = 10;
+/** What the registry stores for one offer. */
+export interface HandoffOfferRecord {
+    OfferID: string;
+    RoomName: string;
+    /** The person the offer was made to. Server-side only. */
+    TargetUserID: string;
+    Mode: HandoffMode;
+    Summary: string;
+    CallerLabel: string;
+    AgentName: string;
+    Status: HandoffOfferStatus;
+    CreatedAtMs: number;
+    ExpiresAtMs: number;
+    /** When the offer left `Pending`, for retention. */
+    ResolvedAtMs?: number;
+    InteractionID?: string;
+    OfferedByAgentID?: string | null;
+}
+/** What it takes to create an offer. */
+export interface CreateOfferInput {
+    RoomName: string;
+    TargetUserID: string;
+    Mode: HandoffMode;
+    Summary: string;
+    CallerLabel: string;
+    AgentName: string;
+    InteractionID?: string;
+    OfferedByAgentID?: string | null;
+    ContextUser?: UserInfo;
+    Provider?: IMetadataProvider;
+}
+/** The result of trying to resolve an offer on a person's behalf. */
+export type ResolveOfferResult = {
+    Ok: true;
+    Offer: HandoffOfferRecord;
+} | {
+    Ok: false;
+    Reason: string;
+};
+/** The one answer for "no such offer", "not yours" and "too late", so an offer's existence is not leaked. */
+export declare const OFFER_UNAVAILABLE = "This conversation offer is no longer available.";
+/** Converts a stored offer to what a console may see. */
+export declare function ToOfferView(offer: HandoffOfferRecord): HandoffOfferView;
+export interface HandoffOfferRegistryDeps {
+    Provider?: IMetadataProvider;
+    ContextUser?: UserInfo;
+    Publisher?: (event: {
+        UserID: string;
+        Kind: 'offered' | 'updated';
+        Offer: HandoffOfferView;
+    }) => void;
+}
+/** Holds handoff offers in `MJ: Interaction Offers` with in-memory caching and compare-and-set concurrency guards. */
+export declare class HandoffOfferRegistry extends BaseSingleton<HandoffOfferRegistry> {
+    private deps;
+    private readonly offers;
+    private now;
+    private sweepTimer?;
+    protected constructor();
+    /** The process-wide registry. */
+    static get Instance(): HandoffOfferRegistry;
+    /** Configures collaborator dependencies. */
+    Configure(deps: HandoffOfferRegistryDeps): void;
+    /** Stops the periodic background sweep timer (shutdown, tests). */
+    StopPeriodicSweep(): void;
+    /** Replaces the clock (tests). */
+    SetClock(now: () => number): void;
+    /** Forgets every cached offer (tests, shutdown). */
+    Clear(): void;
+    /**
+     * Creates a pending offer. Refuses when the person already has {@link MAX_PENDING_OFFERS_PER_USER} pending.
+     *
+     * @returns The new offer, or `undefined` when the person's pending-offer cap is reached.
+     */
+    Create(input: CreateOfferInput, timeoutMs?: number): Promise<HandoffOfferRecord | undefined>;
+    /** The offer with this id, or `undefined`. */
+    Get(offerID: string, contextUser?: UserInfo, provider?: IMetadataProvider): Promise<HandoffOfferRecord | undefined>;
+    /** The person's offers that can still be accepted, soonest to expire first. */
+    PendingForUser(userID: string, contextUser?: UserInfo, provider?: IMetadataProvider): Promise<HandoffOfferRecord[]>;
+    /** The person's offers to show: pending ones, plus ones resolved recently enough to still be retained. */
+    ListForUser(userID: string, contextUser?: UserInfo, provider?: IMetadataProvider): Promise<HandoffOfferRecord[]>;
+    /** The offers made from one room, any status. */
+    ForRoom(roomName: string, contextUser?: UserInfo, provider?: IMetadataProvider): Promise<HandoffOfferRecord[]>;
+    /**
+     * Moves a pending offer to a terminal status on behalf of the person it was made to. The caller must be the
+     * offer's target and the offer must still be pending and unexpired; anything else answers the same way.
+     *
+     * Compares and sets atomically in a transaction on `Status = 'Pending'` so concurrent requests across
+     * multiple instances cannot both succeed.
+     */
+    ResolveForUser(offerID: string, userID: string, status: 'Accepted' | 'Declined', contextUser?: UserInfo, provider?: IMetadataProvider): Promise<ResolveOfferResult>;
+    /**
+     * Moves a pending offer to `Expired` or `Cancelled` (a system decision, not the person's).
+     *
+     * @returns The offer when it was pending and has now changed; `undefined` when it was already resolved or unknown.
+     */
+    Close(offerID: string, status: 'Expired' | 'Cancelled', contextUser?: UserInfo, provider?: IMetadataProvider): Promise<HandoffOfferRecord | undefined>;
+    /**
+     * Sweeps expired pending offers and purges retained resolved offers.
+     *
+     * @returns How many pending offers were expired by this sweep.
+     */
+    Sweep(contextUser?: UserInfo, provider?: IMetadataProvider): Promise<number>;
+    private sweep;
+    private finish;
+    private entityToRecord;
+    private notifyPublisher;
+    private getProvider;
+    private getRunView;
+}
+//# sourceMappingURL=handoff-offer-registry.d.ts.map

package/dist/room-handoff/handoff-offer-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handoff-offer-registry.d.ts","sourceRoot":"","sources":["../../src/room-handoff/handoff-offer-registry.ts"],"names":[],"mappings":"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"}

package/dist/room-handoff/handoff-offer-registry.js

@@ -0,0 +1,521 @@
+/**
+ * @fileoverview Durable registry of handoff offers backed by `MJ: Interaction Offers`.
+ *
+ * An offer is a short-lived question put to one person: "a caller is waiting, will you take the conversation?".
+ * It lives in `MJ: Interaction Offers` from the moment the AI asks until it is accepted, declined, expired or cancelled,
+ * and is kept so a console that was open when it resolved can still show what happened.
+ *
+ * **Durable and cluster-safe.** Offers are stored in the database (`MJ: Interaction Offers`). Accept and decline
+ * execute a compare-and-set on `Status = 'Pending'` inside `RunInEntityTransaction` so multiple server instances
+ * cannot both accept or race. Expired offers are updated on read and through a periodic sweep. Live changes are
+ * published locally and across instances via cluster pub/sub.
+ *
+ * An accept or decline is authorised by comparing the offer's target user with the caller, and a mismatch answers
+ * exactly as a missing offer does: someone who does not own an offer cannot learn that it exists.
+ *
+ * @module @memberjunction/livekit-room-server
+ */
+import { randomUUID } from 'node:crypto';
+import { LogError, Metadata, RunInEntityTransaction, RunView } from '@memberjunction/core';
+import { BaseSingleton, EscapeSQLString, UUIDsEqual } from '@memberjunction/global';
+/** How long a person has to accept an offer before it expires. */
+export const HANDOFF_OFFER_TIMEOUT_MS = 45_000;
+/** How long a resolved offer stays listed (so a console that was open still sees what happened). */
+export const HANDOFF_OFFER_RETENTION_MS = 5 * 60_000;
+/** The most pending offers one person can have at once; a flood of offers is refused rather than queued. */
+export const MAX_PENDING_OFFERS_PER_USER = 10;
+/** The one answer for "no such offer", "not yours" and "too late", so an offer's existence is not leaked. */
+export const OFFER_UNAVAILABLE = 'This conversation offer is no longer available.';
+/** Converts a stored offer to what a console may see. */
+export function ToOfferView(offer) {
+    return {
+        OfferID: offer.OfferID,
+        RoomName: offer.RoomName,
+        Mode: offer.Mode,
+        Summary: offer.Summary,
+        CallerLabel: offer.CallerLabel,
+        AgentName: offer.AgentName,
+        Status: offer.Status,
+        CreatedAt: new Date(offer.CreatedAtMs).toISOString(),
+        ExpiresAt: new Date(offer.ExpiresAtMs).toISOString(),
+        InteractionID: offer.InteractionID ?? null,
+    };
+}
+function asTransactionCapable(provider) {
+    if (!provider)
+        return undefined;
+    const candidate = provider;
+    return candidate.SupportsEntityTransactions === true && typeof candidate.BeginEntityTransaction === 'function'
+        ? candidate
+        : undefined;
+}
+/** Holds handoff offers in `MJ: Interaction Offers` with in-memory caching and compare-and-set concurrency guards. */
+export class HandoffOfferRegistry extends BaseSingleton {
+    constructor() {
+        super();
+        this.deps = {};
+        this.offers = new Map();
+        this.now = Date.now;
+        this.sweepTimer = setInterval(() => {
+            void this.Sweep().catch((e) => {
+                LogError(`[HandoffOfferRegistry] periodic sweep failed: ${e instanceof Error ? e.message : String(e)}`);
+            });
+        }, 15_000);
+        this.sweepTimer.unref?.();
+    }
+    /** The process-wide registry. */
+    static get Instance() {
+        return super.getInstance();
+    }
+    /** Configures collaborator dependencies. */
+    Configure(deps) {
+        this.deps = { ...this.deps, ...deps };
+    }
+    /** Stops the periodic background sweep timer (shutdown, tests). */
+    StopPeriodicSweep() {
+        if (this.sweepTimer) {
+            clearInterval(this.sweepTimer);
+            this.sweepTimer = undefined;
+        }
+    }
+    /** Replaces the clock (tests). */
+    SetClock(now) {
+        this.now = now;
+    }
+    /** Forgets every cached offer (tests, shutdown). */
+    Clear() {
+        this.offers.clear();
+    }
+    /**
+     * Creates a pending offer. Refuses when the person already has {@link MAX_PENDING_OFFERS_PER_USER} pending.
+     *
+     * @returns The new offer, or `undefined` when the person's pending-offer cap is reached.
+     */
+    async Create(input, timeoutMs = HANDOFF_OFFER_TIMEOUT_MS) {
+        await this.sweep(input.ContextUser, input.Provider);
+        const pending = await this.PendingForUser(input.TargetUserID, input.ContextUser, input.Provider);
+        if (pending.length >= MAX_PENDING_OFFERS_PER_USER) {
+            return undefined;
+        }
+        const createdAt = this.now();
+        const expiresAt = createdAt + timeoutMs;
+        const p = this.getProvider(input.Provider);
+        if (p && typeof p.GetEntityObject === 'function') {
+            const user = input.ContextUser ?? this.deps.ContextUser;
+            try {
+                let interactionID = input.InteractionID;
+                if (!interactionID) {
+                    const rv = this.getRunView(p);
+                    const existing = await rv.RunView({
+                        EntityName: 'MJ: Interactions',
+                        ExtraFilter: `RoomName = '${EscapeSQLString(input.RoomName.trim())}' AND Status = 'Active'`,
+                        ResultType: 'entity_object',
+                    }, user);
+                    if (existing.Success && existing.Results && existing.Results.length > 0) {
+                        interactionID = existing.Results[0].ID;
+                    }
+                    else {
+                        const interaction = await p.GetEntityObject('MJ: Interactions', user);
+                        interaction.Channel = 'Web';
+                        interaction.Direction = 'Inbound';
+                        interaction.RoomName = input.RoomName;
+                        interaction.Status = 'Active';
+                        interaction.StartedAt = new Date(createdAt);
+                        const savedInteraction = await interaction.Save();
+                        if (savedInteraction) {
+                            interactionID = interaction.ID;
+                        }
+                    }
+                }
+                if (interactionID) {
+                    const entity = await p.GetEntityObject('MJ: Interaction Offers', user);
+                    entity.InteractionID = interactionID;
+                    entity.TargetUserID = input.TargetUserID;
+                    entity.OfferedByAgentID = input.OfferedByAgentID ?? null;
+                    entity.Mode = input.Mode.toLowerCase() === 'warm' ? 'Warm' : 'Blind';
+                    entity.Status = 'Pending';
+                    entity.RoomName = input.RoomName;
+                    entity.CallerLabel = input.CallerLabel;
+                    entity.Summary = input.Summary;
+                    entity.OfferedAt = new Date(createdAt);
+                    entity.ExpiresAt = new Date(expiresAt);
+                    const saved = await entity.Save();
+                    if (saved) {
+                        const record = this.entityToRecord(entity, input.AgentName);
+                        this.offers.set(record.OfferID, record);
+                        return record;
+                    }
+                    LogError(`[HandoffOfferRegistry] Failed to save offer entity: ${entity.LatestResult?.CompleteMessage ?? 'unknown'}`);
+                }
+            }
+            catch (err) {
+                LogError(`[HandoffOfferRegistry] Failed to create database offer: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        // In-memory fallback
+        const offer = {
+            OfferID: randomUUID(),
+            RoomName: input.RoomName,
+            TargetUserID: input.TargetUserID,
+            Mode: input.Mode,
+            Summary: input.Summary,
+            CallerLabel: input.CallerLabel,
+            AgentName: input.AgentName,
+            Status: 'Pending',
+            CreatedAtMs: createdAt,
+            ExpiresAtMs: expiresAt,
+            InteractionID: input.InteractionID,
+            OfferedByAgentID: input.OfferedByAgentID ?? null,
+        };
+        this.offers.set(offer.OfferID, offer);
+        return offer;
+    }
+    /** The offer with this id, or `undefined`. */
+    async Get(offerID, contextUser, provider) {
+        const p = this.getProvider(provider);
+        const now = this.now();
+        if (p && typeof p.GetEntityObject === 'function') {
+            try {
+                const user = contextUser ?? this.deps.ContextUser;
+                const entity = await p.GetEntityObject('MJ: Interaction Offers', user);
+                const loaded = await entity.Load(offerID);
+                if (loaded) {
+                    const expiresAtMs = entity.ExpiresAt ? new Date(entity.ExpiresAt).getTime() : 0;
+                    if (entity.Status === 'Pending' && expiresAtMs <= now) {
+                        entity.Status = 'Expired';
+                        entity.RespondedAt = new Date(now);
+                        await entity.Save();
+                        const record = this.entityToRecord(entity);
+                        this.offers.set(record.OfferID, record);
+                        this.notifyPublisher(record);
+                        return record;
+                    }
+                    const record = this.entityToRecord(entity);
+                    this.offers.set(record.OfferID, record);
+                    return record;
+                }
+            }
+            catch (err) {
+                LogError(`[HandoffOfferRegistry] Get(${offerID}) failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        const cached = this.offers.get(offerID);
+        if (cached && cached.Status === 'Pending' && cached.ExpiresAtMs <= now) {
+            this.finish(cached, 'Expired');
+            this.notifyPublisher(cached);
+        }
+        return cached;
+    }
+    /** The person's offers that can still be accepted, soonest to expire first. */
+    async PendingForUser(userID, contextUser, provider) {
+        const p = this.getProvider(provider);
+        const now = this.now();
+        if (p && typeof p.GetEntityObject === 'function') {
+            try {
+                const rv = this.getRunView(p);
+                const user = contextUser ?? this.deps.ContextUser;
+                const result = await rv.RunView({
+                    EntityName: 'MJ: Interaction Offers',
+                    ExtraFilter: `TargetUserID = '${EscapeSQLString(userID)}' AND Status = 'Pending'`,
+                    OrderBy: 'ExpiresAt ASC',
+                    ResultType: 'entity_object',
+                }, user);
+                if (result.Success && result.Results) {
+                    const records = [];
+                    for (const entity of result.Results) {
+                        const expiresAtMs = entity.ExpiresAt ? new Date(entity.ExpiresAt).getTime() : 0;
+                        if (expiresAtMs <= now) {
+                            entity.Status = 'Expired';
+                            entity.RespondedAt = new Date(now);
+                            await entity.Save();
+                            const rec = this.entityToRecord(entity);
+                            this.offers.set(rec.OfferID, rec);
+                            this.notifyPublisher(rec);
+                        }
+                        else {
+                            const rec = this.entityToRecord(entity);
+                            this.offers.set(rec.OfferID, rec);
+                            records.push(rec);
+                        }
+                    }
+                    return records.sort((a, b) => a.ExpiresAtMs - b.ExpiresAtMs);
+                }
+            }
+            catch (err) {
+                LogError(`[HandoffOfferRegistry] PendingForUser query failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        // In-memory fallback
+        return [...this.offers.values()]
+            .filter((o) => o.Status === 'Pending' && o.ExpiresAtMs > now && UUIDsEqual(o.TargetUserID, userID))
+            .sort((a, b) => a.ExpiresAtMs - b.ExpiresAtMs);
+    }
+    /** The person's offers to show: pending ones, plus ones resolved recently enough to still be retained. */
+    async ListForUser(userID, contextUser, provider) {
+        await this.sweep(contextUser, provider);
+        const p = this.getProvider(provider);
+        const now = this.now();
+        if (p && typeof p.GetEntityObject === 'function') {
+            try {
+                const cutoff = new Date(now - HANDOFF_OFFER_RETENTION_MS).toISOString();
+                const rv = this.getRunView(p);
+                const user = contextUser ?? this.deps.ContextUser;
+                const result = await rv.RunView({
+                    EntityName: 'MJ: Interaction Offers',
+                    ExtraFilter: `TargetUserID = '${EscapeSQLString(userID)}' AND (Status = 'Pending' OR RespondedAt >= '${cutoff}')`,
+                    OrderBy: 'OfferedAt DESC',
+                    ResultType: 'entity_object',
+                }, user);
+                if (result.Success && result.Results) {
+                    const records = result.Results.map((e) => {
+                        const rec = this.entityToRecord(e);
+                        this.offers.set(rec.OfferID, rec);
+                        return rec;
+                    });
+                    return records.sort((a, b) => b.CreatedAtMs - a.CreatedAtMs);
+                }
+            }
+            catch (err) {
+                LogError(`[HandoffOfferRegistry] ListForUser query failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        // In-memory fallback
+        return [...this.offers.values()]
+            .filter((o) => UUIDsEqual(o.TargetUserID, userID))
+            .sort((a, b) => b.CreatedAtMs - a.CreatedAtMs);
+    }
+    /** The offers made from one room, any status. */
+    async ForRoom(roomName, contextUser, provider) {
+        const key = roomName.trim().toLowerCase();
+        const p = this.getProvider(provider);
+        if (p && typeof p.GetEntityObject === 'function') {
+            try {
+                const rv = this.getRunView(p);
+                const user = contextUser ?? this.deps.ContextUser;
+                const result = await rv.RunView({
+                    EntityName: 'MJ: Interaction Offers',
+                    ExtraFilter: `RoomName = '${EscapeSQLString(roomName.trim())}'`,
+                    OrderBy: 'OfferedAt DESC',
+                    ResultType: 'entity_object',
+                }, user);
+                if (result.Success && result.Results) {
+                    return result.Results.map((e) => this.entityToRecord(e));
+                }
+            }
+            catch (err) {
+                LogError(`[HandoffOfferRegistry] ForRoom query failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        // In-memory fallback
+        return [...this.offers.values()].filter((o) => o.RoomName.trim().toLowerCase() === key);
+    }
+    /**
+     * Moves a pending offer to a terminal status on behalf of the person it was made to. The caller must be the
+     * offer's target and the offer must still be pending and unexpired; anything else answers the same way.
+     *
+     * Compares and sets atomically in a transaction on `Status = 'Pending'` so concurrent requests across
+     * multiple instances cannot both succeed.
+     */
+    async ResolveForUser(offerID, userID, status, contextUser, provider) {
+        const p = this.getProvider(provider);
+        if (p && typeof p.GetEntityObject === 'function') {
+            const user = contextUser ?? this.deps.ContextUser;
+            try {
+                return await RunInEntityTransaction(asTransactionCapable(p), async () => {
+                    const entity = await p.GetEntityObject('MJ: Interaction Offers', user);
+                    const loaded = await entity.Load(offerID);
+                    if (!loaded) {
+                        return { Ok: false, Reason: OFFER_UNAVAILABLE };
+                    }
+                    if (!UUIDsEqual(entity.TargetUserID, userID)) {
+                        return { Ok: false, Reason: OFFER_UNAVAILABLE };
+                    }
+                    const now = this.now();
+                    const expiresAtMs = entity.ExpiresAt ? new Date(entity.ExpiresAt).getTime() : 0;
+                    if (entity.Status !== 'Pending' || expiresAtMs <= now) {
+                        if (entity.Status === 'Pending' && expiresAtMs <= now) {
+                            entity.Status = 'Expired';
+                            entity.RespondedAt = new Date(now);
+                            await entity.Save();
+                            const rec = this.entityToRecord(entity);
+                            this.offers.set(rec.OfferID, rec);
+                            this.notifyPublisher(rec);
+                        }
+                        return { Ok: false, Reason: OFFER_UNAVAILABLE };
+                    }
+                    entity.Status = status;
+                    entity.RespondedAt = new Date(now);
+                    const saved = await entity.Save();
+                    if (!saved) {
+                        return { Ok: false, Reason: OFFER_UNAVAILABLE };
+                    }
+                    const record = this.entityToRecord(entity);
+                    this.offers.set(record.OfferID, record);
+                    this.notifyPublisher(record);
+                    return { Ok: true, Offer: record };
+                });
+            }
+            catch (err) {
+                LogError(`[HandoffOfferRegistry] ResolveForUser transaction failed: ${err instanceof Error ? err.message : String(err)}`);
+                return { Ok: false, Reason: OFFER_UNAVAILABLE };
+            }
+        }
+        // In-memory fallback
+        const offer = this.offers.get(offerID);
+        if (!offer || !UUIDsEqual(offer.TargetUserID, userID)) {
+            return { Ok: false, Reason: OFFER_UNAVAILABLE };
+        }
+        if (offer.Status !== 'Pending' || offer.ExpiresAtMs <= this.now()) {
+            return { Ok: false, Reason: OFFER_UNAVAILABLE };
+        }
+        this.finish(offer, status);
+        this.notifyPublisher(offer);
+        return { Ok: true, Offer: offer };
+    }
+    /**
+     * Moves a pending offer to `Expired` or `Cancelled` (a system decision, not the person's).
+     *
+     * @returns The offer when it was pending and has now changed; `undefined` when it was already resolved or unknown.
+     */
+    async Close(offerID, status, contextUser, provider) {
+        const p = this.getProvider(provider);
+        if (p && typeof p.GetEntityObject === 'function') {
+            const user = contextUser ?? this.deps.ContextUser;
+            try {
+                return await RunInEntityTransaction(asTransactionCapable(p), async () => {
+                    const entity = await p.GetEntityObject('MJ: Interaction Offers', user);
+                    const loaded = await entity.Load(offerID);
+                    if (!loaded || entity.Status !== 'Pending') {
+                        return undefined;
+                    }
+                    entity.Status = status;
+                    entity.RespondedAt = new Date(this.now());
+                    const saved = await entity.Save();
+                    if (!saved) {
+                        return undefined;
+                    }
+                    const record = this.entityToRecord(entity);
+                    this.offers.set(record.OfferID, record);
+                    this.notifyPublisher(record);
+                    return record;
+                });
+            }
+            catch (err) {
+                LogError(`[HandoffOfferRegistry] Close transaction failed: ${err instanceof Error ? err.message : String(err)}`);
+                return undefined;
+            }
+        }
+        // In-memory fallback
+        const offer = this.offers.get(offerID);
+        if (!offer || offer.Status !== 'Pending') {
+            return undefined;
+        }
+        this.finish(offer, status);
+        this.notifyPublisher(offer);
+        return offer;
+    }
+    /**
+     * Sweeps expired pending offers and purges retained resolved offers.
+     *
+     * @returns How many pending offers were expired by this sweep.
+     */
+    async Sweep(contextUser, provider) {
+        return this.sweep(contextUser, provider);
+    }
+    async sweep(contextUser, provider) {
+        const now = this.now();
+        let swept = 0;
+        const p = this.getProvider(provider);
+        if (p && typeof p.GetEntityObject === 'function') {
+            try {
+                const rv = this.getRunView(p);
+                const user = contextUser ?? this.deps.ContextUser;
+                const result = await rv.RunView({
+                    EntityName: 'MJ: Interaction Offers',
+                    ExtraFilter: `Status = 'Pending' AND ExpiresAt <= '${new Date(now).toISOString()}'`,
+                    ResultType: 'entity_object',
+                }, user);
+                if (result.Success && result.Results) {
+                    for (const entity of result.Results) {
+                        entity.Status = 'Expired';
+                        entity.RespondedAt = new Date(now);
+                        const saved = await entity.Save();
+                        if (saved) {
+                            const record = this.entityToRecord(entity);
+                            this.offers.set(record.OfferID, record);
+                            this.notifyPublisher(record);
+                            swept++;
+                        }
+                    }
+                }
+            }
+            catch (e) {
+                LogError(`[HandoffOfferRegistry] sweep failed: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        }
+        const cutoff = now - HANDOFF_OFFER_RETENTION_MS;
+        for (const [id, offer] of this.offers) {
+            if (offer.Status === 'Pending' && offer.ExpiresAtMs <= now) {
+                this.finish(offer, 'Expired');
+                this.notifyPublisher(offer);
+                swept++;
+            }
+            if (offer.ResolvedAtMs !== undefined && offer.ResolvedAtMs < cutoff) {
+                this.offers.delete(id);
+            }
+        }
+        return swept;
+    }
+    finish(offer, status) {
+        offer.Status = status;
+        offer.ResolvedAtMs = this.now();
+    }
+    entityToRecord(entity, agentNameFallback) {
+        const createdAtMs = entity.OfferedAt
+            ? new Date(entity.OfferedAt).getTime()
+            : entity.__mj_CreatedAt
+                ? new Date(entity.__mj_CreatedAt).getTime()
+                : this.now();
+        const expiresAtMs = entity.ExpiresAt ? new Date(entity.ExpiresAt).getTime() : createdAtMs + HANDOFF_OFFER_TIMEOUT_MS;
+        const resolvedAtMs = entity.RespondedAt ? new Date(entity.RespondedAt).getTime() : undefined;
+        const mode = (entity.Mode?.toLowerCase() === 'warm' ? 'warm' : 'blind');
+        const agentName = entity.OfferedByAgent || agentNameFallback || 'AI Agent';
+        return {
+            OfferID: entity.ID,
+            InteractionID: entity.InteractionID,
+            OfferedByAgentID: entity.OfferedByAgentID,
+            RoomName: entity.RoomName,
+            TargetUserID: entity.TargetUserID,
+            Mode: mode,
+            Summary: entity.Summary ?? '',
+            CallerLabel: entity.CallerLabel ?? '',
+            AgentName: agentName,
+            Status: entity.Status,
+            CreatedAtMs: createdAtMs,
+            ExpiresAtMs: expiresAtMs,
+            ResolvedAtMs: resolvedAtMs,
+        };
+    }
+    notifyPublisher(record) {
+        try {
+            this.deps.Publisher?.({
+                UserID: record.TargetUserID,
+                Kind: 'updated',
+                Offer: ToOfferView(record),
+            });
+        }
+        catch (e) {
+            LogError(`[HandoffOfferRegistry] publish failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    getProvider(callProvider) {
+        return callProvider ?? this.deps.Provider ?? Metadata.Provider;
+    }
+    getRunView(provider) {
+        if (typeof provider.RunView === 'function') {
+            return RunView.FromMetadataProvider(provider);
+        }
+        return new RunView();
+    }
+}
+//# sourceMappingURL=handoff-offer-registry.js.map