@canonmsg/agent-sdk 10.2.0 → 10.3.0

package/dist/work-session-host.js

@@ -0,0 +1,573 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { ApprovalManager, CanonApiError, CanonClient, CanonStream, NativeWorkSessionCreateError, createRuntimeHeartbeat, createRuntimeStatePublisher, initRTDBAuth, resolveCanonRuntimeConnection, verifyCanonRuntimeConnection, } from '@canonmsg/core';
+import { createCanonAttachedSession, } from './attached-session.js';
+import { createWorkSessionJournal } from './work-session-state.js';
+import { createWorkSessionInteractionBridge } from './work-session-interactions.js';
+/** One authenticated transport and liveness publisher, with durable per-room native routes. */
+export function createCanonWorkSessionHost(options) {
+    const connection = { ...options.connection };
+    const runtime = resolveCanonRuntimeConnection({ environmentId: connection.environmentId,
+        apiBaseUrl: connection.baseUrl, streamUrl: connection.streamUrl,
+        rtdbUrl: connection.rtdbUrl, firebaseWebApiKey: connection.firebaseApiKey });
+    const client = new CanonClient(connection.apiKey, runtime.apiBaseUrl);
+    const journal = createWorkSessionJournal(options.store, {
+        environmentId: connection.environmentId, agentId: connection.agentId, hostId: options.hostId,
+    });
+    const pollMs = options.pollIntervalMs ?? 2_000;
+    const heartbeatMs = options.heartbeatIntervalMs ?? 25_000;
+    const connectTimeoutMs = options.connectTimeoutMs ?? 20_000;
+    if (![pollMs, heartbeatMs, connectTimeoutMs].every((n) => Number.isFinite(n) && n > 0)
+        || heartbeatMs > 30_000 || !options.hostId.trim())
+        throw new Error('Invalid work-session host configuration.');
+    const runtimeEpoch = randomUUID();
+    const rooms = new Map();
+    const handlers = new Set();
+    const pending = new Set();
+    let broker;
+    let manager;
+    let publisher;
+    let heartbeat;
+    let transport;
+    let stream;
+    let connected = false;
+    let stopped = false;
+    let startPromise;
+    let stopPromise;
+    let cleanupPromise;
+    let pollTimer;
+    let leaseTimer;
+    let expiryTimer;
+    let processing;
+    let renewing;
+    let rejectConnection;
+    let resolveConnection;
+    const report = (error, operation) => { try {
+        options.onError?.(error, operation);
+    }
+    catch { /* observer */ } };
+    const emit = (event) => {
+        try {
+            options.onStatus?.(event);
+        }
+        catch (error) {
+            report(error, 'status');
+        }
+    };
+    function auth() {
+        if (!broker)
+            throw new Error('Work-session runtime is not registered.');
+        return { hostId: options.hostId, runtimeEpoch, leaseToken: broker.lease.leaseToken };
+    }
+    function fence() {
+        if (stopped || !broker || broker.lease.expiresAt - Date.now() < 5_000)
+            throw new Error('Work-session runtime no longer has a fresh lease.');
+    }
+    function retainLease(state) {
+        if (state.lease.hostId !== options.hostId || state.lease.runtimeEpoch !== runtimeEpoch
+            || (broker && state.ownerId !== broker.ownerId))
+            throw new Error('Work-session runtime identity changed.');
+        broker = state;
+        if (expiryTimer)
+            clearTimeout(expiryTimer);
+        expiryTimer = setTimeout(() => fail(new Error('Work-session runtime lease expired.'), 'lease-expired'), Math.max(1, state.lease.expiresAt - Date.now() - 5_000));
+        expiryTimer.unref?.();
+    }
+    function updatePresence() {
+        const ready = connected && !stopped && [...rooms.values()].some((room) => !room.stopped && room.acknowledged && ['ready', 'uncertain'].includes(room.session.getState().status));
+        if (ready)
+            heartbeat?.connect();
+        else
+            void heartbeat?.disconnect().catch((error) => report(error, 'presence'));
+    }
+    function fail(error, operation) {
+        report(error, operation);
+        void stop().catch((stopError) => report(stopError, 'stop'));
+    }
+    function fanout(name, ...args) {
+        for (const handler of [...handlers]) {
+            try {
+                handler[name]?.(...args);
+            }
+            catch (error) {
+                report(error, `stream-${name}`);
+            }
+        }
+    }
+    async function removeRoom(conversationId, releaseBinding) {
+        const room = rooms.get(conversationId);
+        if (!room)
+            return;
+        rooms.delete(conversationId);
+        room.stopped = true;
+        room.controller.abort();
+        try {
+            await room.session.stop();
+        }
+        finally {
+            room.releaseNative();
+            updatePresence();
+        }
+        if (releaseBinding && !stopped) {
+            fence();
+            retainLease(await client.releaseWorkSessionBinding({ ...auth(), conversationId,
+                workSessionId: room.binding.workSessionId }));
+        }
+    }
+    function activate(conversationId) {
+        const room = rooms.get(conversationId);
+        if (!room || stopped)
+            return;
+        room.acknowledged = true;
+        room.activate();
+        room.session.refreshRuntimeState();
+        updatePresence();
+    }
+    async function attach(binding, confirmed = false) {
+        fence();
+        const existing = rooms.get(binding.conversationId);
+        if (existing && existing.binding.nativeSessionId === binding.nativeSessionId && !existing.stopped) {
+            if (confirmed)
+                activate(binding.conversationId);
+            return;
+        }
+        if (existing)
+            throw new Error('This conversation already has a work session.');
+        if ([...rooms.values()].some((room) => room.binding.nativeSessionId === binding.nativeSessionId))
+            throw new Error('This native session already has a different Canon audience.');
+        const conversation = (await client.getConversations()).find((entry) => entry.id === binding.conversationId);
+        if (!conversation?.memberIds.includes(connection.agentId) || !conversation.memberIds.includes(broker.ownerId))
+            throw new Error('The owner and agent must both be members of this conversation.');
+        fence();
+        const nativeBinding = { ...binding, environmentId: connection.environmentId, agentId: connection.agentId };
+        const releaseNative = await options.acquireNativeSession(nativeBinding);
+        const controller = new AbortController();
+        let activateRoute;
+        const routeReady = new Promise((resolve) => { activateRoute = resolve; });
+        controller.signal.addEventListener('abort', activateRoute, { once: true });
+        let session;
+        let adapter;
+        try {
+            fence();
+            const bridge = createWorkSessionInteractionBridge({ manager: manager, journal,
+                hostId: options.hostId, conversationId: binding.conversationId, ownerId: broker.ownerId,
+                onPendingChange: (value) => {
+                    if (value)
+                        pending.add(binding.conversationId);
+                    else
+                        pending.delete(binding.conversationId);
+                    session?.refreshRuntimeState();
+                } });
+            adapter = await options.provider.open(binding.nativeSessionId, {
+                request: async (request, nativeOptions) => {
+                    const combined = new AbortController();
+                    const abort = () => combined.abort();
+                    controller.signal.addEventListener('abort', abort, { once: true });
+                    nativeOptions.signal.addEventListener('abort', abort, { once: true });
+                    if (controller.signal.aborted || nativeOptions.signal.aborted || stopped)
+                        combined.abort();
+                    try {
+                        // A resumed native approval can arrive during attachment. Wait for
+                        // Canon's binding acknowledgement before exposing its contents.
+                        const nativeAborted = new Promise((resolve) => combined.signal.addEventListener('abort', () => resolve(), { once: true }));
+                        if (combined.signal.aborted)
+                            return { kind: 'cancelled' };
+                        await Promise.race([routeReady, nativeAborted]);
+                        return await bridge.request(request, { signal: combined.signal });
+                    }
+                    finally {
+                        controller.signal.removeEventListener('abort', abort);
+                        nativeOptions.signal.removeEventListener('abort', abort);
+                    }
+                },
+            });
+            fence();
+            session = createCanonAttachedSession({ connection, binding: nativeBinding, native: adapter,
+                store: options.createSessionStore(nativeBinding), transport,
+                onError: (error, operation) => report(error, `session-${operation}`),
+                onStatus: (status) => {
+                    emit({ status: 'session', conversationId: binding.conversationId, session: status });
+                    if (status.status === 'stopped' && !stopped) {
+                        // Defer until the child's stop promise settles; never await it from its own callback.
+                        queueMicrotask(() => { void removeRoom(binding.conversationId, true).catch((error) => fail(error, 'detach')); });
+                    }
+                    updatePresence();
+                },
+            });
+            rooms.set(binding.conversationId, { binding, session, controller, releaseNative, stopped: false, acknowledged: confirmed, activate: activateRoute });
+            if (confirmed)
+                activateRoute();
+            await session.start();
+            fence();
+            if (session.getState().status !== 'ready')
+                throw new Error('The native session is not ready for Canon input.');
+            updatePresence();
+        }
+        catch (error) {
+            controller.abort();
+            rooms.delete(binding.conversationId);
+            try {
+                if (session)
+                    await session.stop();
+                else
+                    await adapter?.close();
+            }
+            finally {
+                releaseNative();
+                updatePresence();
+            }
+            throw error;
+        }
+    }
+    const fingerprint = (request) => createHash('sha256').update(JSON.stringify([
+        request.agentId, request.conversationId, request.requestId, request.hostId,
+        request.runtimeEpoch, request.catalogRevision, request.selection, request.requestedBy,
+    ])).digest('hex');
+    const errorResult = (status, code, message) => ({ status, error: { code, message } });
+    async function processRequest(request, replayed) {
+        if (request.status !== 'claimed' && request.status !== 'uncertain')
+            return;
+        fence();
+        const hash = fingerprint(request);
+        let operation = journal.read().operations.find((entry) => entry.request.requestId === request.requestId);
+        if (operation && operation.fingerprint !== hash)
+            throw new Error('Work-session request changed during recovery.');
+        if (!operation) {
+            const completion = replayed ? errorResult('uncertain', 'local_state_missing', 'This request was already claimed, but its local record is unavailable. Select the existing native session to recover.') : undefined;
+            operation = { request, fingerprint: hash, phase: completion ? 'complete' : request.selection.mode === 'create' ? 'creating' : 'created',
+                ...(completion ? { completion } : request.selection.mode === 'attach' ? { nativeSessionId: request.selection.sessionId, settings: {} } : {}) };
+            await journal.mutate((state) => { state.operations.push(operation); });
+            if (!completion && request.selection.mode === 'create') {
+                let created;
+                try {
+                    fence();
+                    created = await options.provider.create(request.selection, {
+                        requestId: request.requestId, conversationId: request.conversationId, agentId: connection.agentId,
+                    });
+                }
+                catch (error) {
+                    const definite = error instanceof NativeWorkSessionCreateError && error.outcome === 'not_created';
+                    const result = errorResult(definite ? 'failed' : 'uncertain', definite ? 'native_create_failed' : 'native_create_uncertain', definite ? 'The native runtime could not create this session. Refresh setup and try again.'
+                        : 'The native runtime may have created this session. Inspect existing sessions before trying again.');
+                    await saveCompletion(request.requestId, result);
+                    report(error, 'native-create');
+                    operation = journal.read().operations.find((entry) => entry.request.requestId === request.requestId);
+                }
+                if (created) {
+                    // The exact ID must reach durable storage before any observer or Canon input can attach.
+                    await journal.mutate((state) => {
+                        const entry = state.operations.find((item) => item.request.requestId === request.requestId);
+                        Object.assign(entry, { phase: 'created', nativeSessionId: created.nativeSessionId, settings: created.settings });
+                    });
+                    operation = journal.read().operations.find((entry) => entry.request.requestId === request.requestId);
+                }
+            }
+        }
+        else if (operation.phase === 'creating') {
+            await saveCompletion(request.requestId, errorResult('uncertain', 'native_create_uncertain', 'The previous process stopped during native creation. Inspect existing sessions before trying again.'));
+            operation = journal.read().operations.find((entry) => entry.request.requestId === request.requestId);
+        }
+        fence();
+        if (!operation.completion) {
+            const nativeSessionId = operation.nativeSessionId;
+            if (!nativeSessionId)
+                throw new Error('Work-session journal has no native session to attach.');
+            const catalog = await options.provider.catalog();
+            const settings = request.selection.mode === 'attach'
+                ? catalog.sessions.find((entry) => entry.id === nativeSessionId)?.settings : operation.settings;
+            if (!settings) {
+                await saveCompletion(request.requestId, errorResult('failed', 'native_session_unavailable', 'The selected native session is no longer loaded. Load it and select it again.'));
+            }
+            else {
+                await journal.mutate((state) => { state.operations.find((entry) => entry.request.requestId === request.requestId).phase = 'attaching'; });
+                try {
+                    await attach({ workSessionId: request.requestId, conversationId: request.conversationId,
+                        hostId: options.hostId, provider: catalog.provider, nativeSessionId, settings, createdAt: Date.now() });
+                    await saveCompletion(request.requestId, { status: 'attached', nativeSessionId, settings });
+                }
+                catch (error) {
+                    await removeRoom(request.conversationId, false);
+                    report(error, 'native-attach');
+                    await saveCompletion(request.requestId, errorResult('failed', 'native_attach_failed', 'Canon could not attach this native session. The native session is retained; select it again after reconnecting.'));
+                }
+            }
+            operation = journal.read().operations.find((entry) => entry.request.requestId === request.requestId);
+        }
+        fence();
+        // A previous process may have saved its successful result before Canon
+        // received it. Reestablish that exact route before confirming readiness.
+        if (operation.completion?.status === 'attached' && !rooms.has(request.conversationId)) {
+            try {
+                await attach({ workSessionId: request.requestId, conversationId: request.conversationId,
+                    hostId: options.hostId, provider: (await options.provider.catalog()).provider,
+                    nativeSessionId: operation.completion.nativeSessionId, settings: operation.completion.settings,
+                    createdAt: request.createdAt });
+            }
+            catch (error) {
+                await removeRoom(request.conversationId, false);
+                report(error, 'recover-attachment');
+                // The explicit claim says Canon has no successful binding yet. Preserve
+                // the native ID for inspection, but do not claim this route is ready.
+                await saveCompletion(request.requestId, errorResult('failed', 'native_restore_failed', 'The saved native session could not be reconnected. Load it and select it again.'));
+                operation = journal.read().operations.find((entry) => entry.request.requestId === request.requestId);
+            }
+        }
+        try {
+            const completed = await client.completeWorkSessionRequest({ ...auth(), requestId: request.requestId, result: operation.completion });
+            if (completed.status !== operation.completion.status) {
+                await removeRoom(request.conversationId, false);
+                throw new Error('Canon did not acknowledge the requested work-session outcome.');
+            }
+            await journal.mutate((state) => { state.operations.find((entry) => entry.request.requestId === request.requestId).acknowledged = true; });
+            if (completed.status === 'attached')
+                activate(request.conversationId);
+        }
+        catch (error) {
+            // An unacknowledged bridge must not accept fresh work. The durable completion can be retried.
+            await removeRoom(request.conversationId, false);
+            throw error;
+        }
+    }
+    async function saveCompletion(requestId, completion) {
+        await journal.mutate((state) => {
+            const entry = state.operations.find((item) => item.request.requestId === requestId);
+            entry.phase = 'complete';
+            entry.completion = completion;
+        });
+    }
+    async function doReconcile() {
+        fence();
+        if (!connected)
+            return;
+        // Finish durable outcomes before taking more work. Explicit claim allows same-host recovery.
+        const outstanding = journal.read().operations.find((entry) => !entry.acknowledged && !entry.quarantined);
+        let claimed;
+        try {
+            claimed = await client.claimWorkSessionRequest({ ...auth(), ...(outstanding ? { requestId: outstanding.request.requestId } : {}) });
+        }
+        catch (error) {
+            if (outstanding && error instanceof CanonApiError && error.code === 'WORK_SESSION_MEMBERSHIP_REQUIRED') {
+                await quarantine(outstanding.request.requestId, 'Conversation membership is no longer available.');
+                return;
+            }
+            if (error instanceof CanonApiError && (error.status === 401 || error.status === 403 || error.code === 'WORK_SESSION_LEASE_STALE'))
+                fail(error, 'request-authority');
+            throw error;
+        }
+        fence();
+        if (!claimed.request) {
+            if (outstanding)
+                await quarantine(outstanding.request.requestId, 'This saved request is no longer available to this runtime.');
+            return;
+        }
+        if (['attached', 'failed', 'expired'].includes(claimed.request.status)) {
+            if (outstanding) {
+                if (claimed.request.status === 'attached' && claimed.request.binding) {
+                    try {
+                        await attach(claimed.request.binding, true);
+                    }
+                    catch (error) {
+                        report(error, 'recover-confirmed-attachment');
+                        fence();
+                        retainLease(await client.releaseWorkSessionBinding({ ...auth(), conversationId: claimed.request.conversationId,
+                            workSessionId: claimed.request.binding.workSessionId }));
+                    }
+                }
+                else
+                    await removeRoom(outstanding.request.conversationId, false);
+                await journal.mutate((state) => { state.operations.find((entry) => entry.request.requestId === outstanding.request.requestId).acknowledged = true; });
+            }
+            return;
+        }
+        await processRequest(claimed.request, claimed.replayed);
+    }
+    async function quarantine(requestId, reason) {
+        const operation = journal.read().operations.find((entry) => entry.request.requestId === requestId);
+        if (!operation)
+            return;
+        await removeRoom(operation.request.conversationId, false);
+        await journal.mutate((state) => { state.operations.find((entry) => entry.request.requestId === requestId).quarantined = reason; });
+        report(new Error(reason), 'request-quarantined');
+    }
+    function reconcile() {
+        if (stopped)
+            return Promise.resolve();
+        processing ??= doReconcile().finally(() => { processing = undefined; });
+        return processing;
+    }
+    async function renew() {
+        fence();
+        const conversations = await client.getConversations();
+        for (const room of [...rooms.values()]) {
+            const conversation = conversations.find((entry) => entry.id === room.binding.conversationId);
+            if (!conversation?.memberIds.includes(connection.agentId) || !conversation.memberIds.includes(broker.ownerId))
+                await removeRoom(room.binding.conversationId, true);
+        }
+        // Catalog has its own freshness deadline; it is refreshed independently of public presence.
+        const catalog = await options.provider.catalog();
+        fence();
+        const state = await client.heartbeatWorkSessionRuntime({ ...auth(), catalog });
+        if (!stopped)
+            retainLease(state);
+    }
+    function start() {
+        if (stopped)
+            return Promise.reject(new Error('Work-session host has stopped.'));
+        startPromise ??= (async () => {
+            await journal.load();
+            await verifyCanonRuntimeConnection(runtime);
+            const identity = await client.getAuthToken();
+            if (identity.agentId !== connection.agentId)
+                throw new Error('Canon credential belongs to a different agent.');
+            if (stopped)
+                return;
+            const catalog = await options.provider.catalog();
+            if (stopped)
+                return;
+            retainLease(await client.registerWorkSessionRuntime({ hostId: options.hostId, runtimeEpoch, displayName: options.displayName, catalog }));
+            if (stopped) {
+                fenceShutdown();
+                return;
+            }
+            // Native history inspection/restoration can be slower than one lease.
+            // Keep the acquired lease alive throughout startup, not only after every
+            // room has finished attaching. This timer advertises no public presence.
+            leaseTimer = setInterval(() => {
+                if (renewing || stopped)
+                    return;
+                renewing = renew().catch((error) => fail(error, 'lease-renewal')).finally(() => { renewing = undefined; });
+            }, heartbeatMs);
+            leaseTimer.unref?.();
+            manager = new ApprovalManager(client, connection.agentId, broker.ownerId);
+            publisher = createRuntimeStatePublisher({ agentId: connection.agentId, clientType: connection.clientType ?? 'generic', hostMode: false,
+                rtdb: initRTDBAuth(client, { rtdbUrl: runtime.rtdbUrl, firebaseApiKey: runtime.firebaseWebApiKey }) });
+            heartbeat = createRuntimeHeartbeat({ publisher, onError: report,
+                getRuntime: () => ({ runtimeDescriptor: { coreControls: [], runtimeControls: [], commands: [],
+                        supportsInterrupt: false, supportsInputInterrupt: false, streamingTextMode: 'snapshot' } }) });
+            transport = { agentId: connection.agentId, environmentId: connection.environmentId, client, publisher,
+                hasPendingInteraction: (id) => pending.has(id),
+                isRouteActive: (id) => !stopped && rooms.get(id)?.acknowledged === true,
+                subscribe: (handler) => { handlers.add(handler); if (connected && !stopped)
+                    handler.onConnected?.(); return () => { handlers.delete(handler); }; } };
+            const connectionReady = new Promise((resolve, reject) => { resolveConnection = resolve; rejectConnection = reject; });
+            const connectionTimer = setTimeout(() => rejectConnection?.(new Error('Canon stream did not connect; work-session setup was not started.')), connectTimeoutMs);
+            stream = new CanonStream({ apiKey: connection.apiKey, agentId: connection.agentId, streamUrl: runtime.streamUrl, handler: {
+                    onMessage: (payload) => {
+                        if (stopped || !connected)
+                            return;
+                        manager?.handleMessage(payload.conversationId, payload.message);
+                        fanout('onMessage', payload);
+                    },
+                    onAgentContext: (context) => {
+                        if (context.agentId !== connection.agentId) {
+                            fail(new Error('Canon stream identity changed.'), 'stream-identity');
+                            return;
+                        }
+                        fanout('onAgentContext', context);
+                    },
+                    onConversationUpdated: (payload) => {
+                        const members = payload.changes.memberIds;
+                        if ((Array.isArray(members) && !members.includes(broker.ownerId))
+                            || payload.membershipChange?.removedMemberIds.includes(broker.ownerId)) {
+                            void removeRoom(payload.conversationId, true).catch((error) => fail(error, 'owner-membership'));
+                        }
+                        fanout('onConversationUpdated', payload);
+                    },
+                    onParticipationSuppressed: (payload) => fanout('onParticipationSuppressed', payload),
+                    onReplayExpired: (payload) => fanout('onReplayExpired', payload),
+                    onConnected: () => { if (stopped)
+                        return; connected = true; resolveConnection?.(); fanout('onConnected'); updatePresence(); },
+                    onDisconnected: () => { connected = false; fanout('onDisconnected'); updatePresence(); },
+                    onError: (error) => report(error, 'stream'),
+                } });
+            void stream.start().catch((error) => { rejectConnection?.(error); report(error, 'stream-start'); });
+            try {
+                await connectionReady;
+            }
+            finally {
+                clearTimeout(connectionTimer);
+                resolveConnection = undefined;
+                rejectConnection = undefined;
+            }
+            fence();
+            // Confirmed same-host routes survive a graceful stop; subscriptions/history remain durable.
+            for (const binding of broker.bindings) {
+                try {
+                    await attach(binding, true);
+                }
+                catch (error) {
+                    report(error, 'restore-session');
+                    fence();
+                    retainLease(await client.releaseWorkSessionBinding({ ...auth(), conversationId: binding.conversationId, workSessionId: binding.workSessionId }));
+                }
+            }
+            fence();
+            pollTimer = setInterval(() => { void reconcile().catch((error) => report(error, 'request')); }, pollMs);
+            pollTimer.unref?.();
+            emit({ status: 'available' });
+            await reconcile();
+        })().catch(async (error) => {
+            // Cleanup cannot await the start promise that is currently unwinding.
+            fenceShutdown();
+            await cleanup().catch((cleanupError) => report(cleanupError, 'startup-cleanup'));
+            throw error;
+        });
+        return startPromise;
+    }
+    function fenceShutdown() {
+        stopped = true;
+        connected = false;
+        if (pollTimer)
+            clearInterval(pollTimer);
+        if (leaseTimer)
+            clearInterval(leaseTimer);
+        if (expiryTimer)
+            clearTimeout(expiryTimer);
+        rejectConnection?.(new Error('Work-session host stopped during startup.'));
+        stream?.stop();
+        manager?.dispose();
+        for (const room of rooms.values()) {
+            room.controller.abort();
+            // Stop input/publication immediately even if another room's create RPC is in flight.
+            void room.session.stop().catch((error) => report(error, 'session-stop'));
+        }
+    }
+    function cleanup() {
+        cleanupPromise ??= (async () => {
+            await Promise.allSettled([processing, renewing].filter(Boolean));
+            await Promise.allSettled([...rooms.keys()].map((id) => removeRoom(id, false)));
+            try {
+                await heartbeat?.dispose();
+            }
+            finally {
+                try {
+                    if (broker)
+                        await client.releaseWorkSessionRuntime(auth());
+                }
+                catch (error) {
+                    report(error, 'release-runtime');
+                }
+                try {
+                    await options.provider.close();
+                }
+                finally {
+                    await journal.close();
+                }
+            }
+            handlers.clear();
+            pending.clear();
+            emit({ status: 'stopped' });
+        })();
+        return cleanupPromise;
+    }
+    function stop() {
+        if (stopPromise)
+            return stopPromise;
+        fenceShutdown();
+        stopPromise = (async () => {
+            await startPromise?.catch(() => { });
+            await cleanup();
+        })();
+        return stopPromise;
+    }
+    return { start, stop, reconcile };
+}

package/dist/work-session-interactions.d.ts

@@ -0,0 +1,12 @@
+import type { ApprovalManager, NativeSessionInteractionBridge } from '@canonmsg/core';
+import type { createWorkSessionJournal } from './work-session-state.js';
+export interface WorkSessionInteractionBridgeOptions {
+    manager: ApprovalManager;
+    journal: ReturnType<typeof createWorkSessionJournal>;
+    hostId: string;
+    conversationId: string;
+    ownerId: string;
+    onPendingChange?: (pending: boolean) => void;
+}
+/** Audience-scoped durability around the shared request manager; it owns all Canon polling and cancellation. */
+export declare function createWorkSessionInteractionBridge(options: WorkSessionInteractionBridgeOptions): NativeSessionInteractionBridge;