@canonmsg/agent-sdk 11.0.3 → 11.1.1

package/dist/attached-session.js

@@ -1,5 +1,5 @@
 import { createHash } from 'node:crypto';
-import { buildChunkedMessagePartMetadata, buildCanonGroupContext, buildCompactGroupContextLines, CanonClient, CanonStream, createAttachedNativeSession, createRuntimeHeartbeat, createRuntimeStatePublisher, initRTDBAuth, resolveCanonRuntimeConnection, splitTextByUtf8Bytes, verifyCanonRuntimeConnection, } from '@canonmsg/core';
+import { buildChunkedMessagePartMetadata, buildCanonGroupContext, buildCompactGroupContextLines, buildSelfContextPromptLines, CanonClient, CanonStream, createAttachedNativeSession, createRuntimeHeartbeat, createRuntimeStatePublisher, initRTDBAuth, hydrateCanonReplyContext, selectInboundSelfContexts, resolveCanonRuntimeConnection, splitTextByUtf8Bytes, verifyCanonRuntimeConnection, } from '@canonmsg/core';
 /**
  * Connect one existing native session to one existing Canon conversation.
  * This is account-level participation, not a second group member. The caller
@@ -236,9 +236,29 @@ export function createCanonAttachedSession(options) {
             }
             const roster = buildCanonGroupContext({ conversation: currentConversation, messages: [message], agentId: binding.agentId, ownerId: currentOwnerId });
             const rosterLines = roster ? buildCompactGroupContextLines(roster, 'initial') : [];
+            const page = await client.getMessagesPage(binding.conversationId, 50).catch(() => null);
+            const replyContext = message.replyTo
+                ? await hydrateCanonReplyContext({
+                    client,
+                    conversationId: binding.conversationId,
+                    message,
+                    messages: page?.messages,
+                })
+                : null;
+            const selectedSelfContext = selectInboundSelfContexts({
+                selfContexts: [...(page?.selfContexts ?? []), ...(payload.selfContexts ?? [])],
+                replyTo: message.replyTo,
+                linkedSelfContextId: page?.activeSelfContextIdByMessageId?.[message.id]
+                    ?? payload.activeSelfContextId,
+                messages: page?.messages,
+                replyContext,
+            });
+            const privateContextLines = buildSelfContextPromptLines(selectedSelfContext.selfContexts, {
+                activeSelfContextId: selectedSelfContext.activeSelfContextId,
+            });
             const result = await core.submit({
                 messageId: message.id,
-                text: [...rosterLines, `Canon message from ${message.senderName ?? message.senderId} (${message.senderType}):\n\n${message.text}`].join('\n\n'),
+                text: [...rosterLines, ...privateContextLines, `Canon message from ${message.senderName ?? message.senderId} (${message.senderType}):\n\n${message.text}`].join('\n\n'),
                 ...(payload.replyAuthority ? { replyAuthority: payload.replyAuthority } : {}),
             });
             // A conclusive provider acknowledgement settles command delivery. Native

package/dist/canon-agent.js

@@ -1,4 +1,4 @@
-import { ApprovalManager, RuntimeRequestManager, runtimeInputDescriptor, runtimeCardDescriptor, CanonClient, ControlChannelPoller, buildCanonTurnContextV2, buildCanonGroupContext, buildParticipationHistorySnapshot, createTurnOutputController, createRuntimeStatePublisher, createRuntimeHeartbeat, createTypingStatusPublisher, diffCanonMemberIds, FINAL_MESSAGE_HANDOFF_MS, RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildRuntimeCardOutcome, buildRuntimeInputOutcome, initRTDBAuth, isChunkedSendMessageError, isPendingCanonOperation, normalizeRuntimeCommandDescriptors, normalizeTurnMetadata, normalizeTurnVerbosityConversationType, reportNoReplyOutcome, hydrateCanonReplyContext, resolveMessageActiveSelfContextId, resolveRuntimeProvenance, resolveTurnVerbosity, resolveConversationPolicyScope, selectActiveSelfContexts, renderCanonHostInboundContent, resolveCanonRuntimeConnection, sendMessageWithRetryChunked, shouldPublishTurnTrail, splitTextByUtf8Bytes, verifyCanonRuntimeConnection, } from '@canonmsg/core';
+import { ApprovalManager, RuntimeRequestManager, runtimeInputDescriptor, runtimeCardDescriptor, CanonClient, ControlChannelPoller, buildCanonTurnContextV2, buildCanonGroupContext, buildParticipationHistorySnapshot, createTurnOutputController, createRuntimeStatePublisher, createRuntimeHeartbeat, createTypingStatusPublisher, diffCanonMemberIds, FINAL_MESSAGE_HANDOFF_MS, RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildRuntimeCardOutcome, buildRuntimeInputOutcome, initRTDBAuth, isChunkedSendMessageError, isPendingCanonOperation, normalizeRuntimeCommandDescriptors, normalizeTurnMetadata, normalizeTurnVerbosityConversationType, reportNoReplyOutcome, hydrateCanonReplyContext, resolveRuntimeProvenance, resolveTurnVerbosity, resolveConversationPolicyScope, selectInboundSelfContexts, renderCanonHostInboundContent, resolveCanonRuntimeConnection, sendMessageWithRetryChunked, shouldPublishTurnTrail, splitTextByUtf8Bytes, verifyCanonRuntimeConnection, } from '@canonmsg/core';
 import { createHash, randomUUID } from 'node:crypto';
 import { Debouncer } from './debouncer.js';
 import { disposeInboundHandoffs, selectInboundHandoffs } from './inbound-handoff.js';
@@ -1628,12 +1628,17 @@ export class CanonAgent {
                     client: this.apiClient, conversationId, message: latestMessage, messages: history,
                 })
                 : null;
-            const resolvedActiveSelfContextId = resolveMessageActiveSelfContextId({
-                messageId: latestMessage?.id,
-                activeSelfContextIdByMessageId: page.activeSelfContextIdByMessageId,
+            const selectedSelfContext = selectInboundSelfContexts({
+                selfContexts: page.selfContexts,
+                replyTo: latestMessage?.replyTo,
+                linkedSelfContextId: latestMessage?.id
+                    ? page.activeSelfContextIdByMessageId?.[latestMessage.id]
+                    : null,
+                messages: page.messages,
+                replyContext,
             });
-            const selfContexts = selectActiveSelfContexts(page.selfContexts, resolvedActiveSelfContextId);
-            const activeSelfContextId = selfContexts.length > 0 ? resolvedActiveSelfContextId : null;
+            const selfContexts = selectedSelfContext.selfContexts;
+            const activeSelfContextId = selectedSelfContext.activeSelfContextId;
             const withActiveSelfContext = (options) => {
                 const base = { ...(options ?? {}) };
                 const withContext = base.selfContextId !== undefined || !activeSelfContextId

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export { CanonAgent } from './canon-agent.js';
+export { createCanonManagedSessionHost } from './managed-session-host.js';
+export type { CanonManagedSessionHostOptions } from './managed-session-host.js';
 export { clearPendingRegistration, ensureAgentProfile, resumeRegistration } from '@canonmsg/core';
 export type { EnsureAgentProfileOptions, RegistrationCredentials, RegistrationProgress, RegistrationSession, RegistrationStatus, RegistrationStore, ResumeRegistrationOptions } from '@canonmsg/core';
 export type { AgentContactsAPI, AgentConversationsAPI, AgentDirectoryAPI, AgentUsersAPI, } from './canon-agent.js';

package/dist/index.js

@@ -1,4 +1,5 @@
 export { CanonAgent } from './canon-agent.js';
+export { createCanonManagedSessionHost } from './managed-session-host.js';
 export { clearPendingRegistration, ensureAgentProfile, resumeRegistration } from '@canonmsg/core';
 export { ApprovalManager, buildApprovalOutcome, buildApprovalReply, buildApprovalRequest, CanonApiError, DEFAULT_APPROVAL_CONFIG, generateApprovalId, HOST_ADMISSION_ACTION_CAPABILITIES, HOST_ADMISSION_ACTIONS_DISABLED, parseApprovalReplyMetadata, parseApprovalRequestMetadata, parseSessionRule, redactSecrets, } from '@canonmsg/core';
 export { SessionManager } from './session-manager.js';

package/dist/managed-session-host.d.ts

@@ -0,0 +1,27 @@
+import { CanonClient, type WorkSessionBinding, type WorkSessionCatalog, type WorkSessionDetailFields, type WorkSessionRequest, type WorkSessionSettings } from '@canonmsg/core';
+import { type WorkSessionHostStore } from './work-session-state.js';
+export interface CanonManagedSessionHostOptions {
+    client: CanonClient;
+    agentId: string;
+    environmentId: string;
+    hostId: string;
+    displayName: string;
+    store: WorkSessionHostStore;
+    catalog(): Promise<WorkSessionCatalog>;
+    /** Must durably save the resolved selection before returning. May be called again after a crash. */
+    configure(request: WorkSessionRequest): Promise<{
+        settings: WorkSessionSettings;
+        fields: WorkSessionDetailFields;
+    }>;
+    onError?: (error: unknown, operation: string) => void;
+    pollIntervalMs?: number;
+    heartbeatIntervalMs?: number;
+}
+/** Broker coordination for a managed host whose ordinary message loop owns turns. */
+export declare function createCanonManagedSessionHost(options: CanonManagedSessionHostOptions): {
+    start: () => Promise<void>;
+    stop: () => Promise<void>;
+    reconcile: () => Promise<void>;
+    report: (conversationId: string, fields: WorkSessionDetailFields, setupState?: "configured" | "attached") => Promise<void>;
+    binding: (conversationId: string) => WorkSessionBinding | undefined;
+};

package/dist/managed-session-host.js

@@ -0,0 +1,195 @@
+import { randomUUID } from 'node:crypto';
+import { CanonApiError, } from '@canonmsg/core';
+import { createWorkSessionJournal } from './work-session-state.js';
+import { createWorkSessionAuthority, fingerprintWorkSessionRequest } from './work-session-coordination.js';
+/** Broker coordination for a managed host whose ordinary message loop owns turns. */
+export function createCanonManagedSessionHost(options) {
+    const journal = createWorkSessionJournal(options.store, {
+        environmentId: options.environmentId, agentId: options.agentId, hostId: options.hostId,
+    });
+    const runtimeEpoch = randomUUID();
+    const pollMs = options.pollIntervalMs ?? 2_000;
+    const heartbeatMs = options.heartbeatIntervalMs ?? 25_000;
+    if (!options.hostId || !Number.isFinite(pollMs) || pollMs <= 0 || !Number.isFinite(heartbeatMs)
+        || heartbeatMs <= 0 || heartbeatMs > 30_000)
+        throw new Error('Invalid managed-session host configuration.');
+    let broker;
+    let stopped = false;
+    const authority = createWorkSessionAuthority({ client: options.client, hostId: options.hostId,
+        runtimeEpoch, displayName: options.displayName, isStopped: () => stopped });
+    let started = false;
+    let pollTimer;
+    let heartbeatTimer;
+    let processing;
+    let renewing;
+    let starting;
+    const reportError = (error, operation) => { try {
+        options.onError?.(error, operation);
+    }
+    catch { /* observer */ } };
+    const auth = authority.auth;
+    const fence = authority.fence;
+    function retain(state) {
+        broker = authority.retain(state);
+    }
+    async function processRequest(request, replayed) {
+        if (request.status !== 'claimed' && request.status !== 'uncertain')
+            return;
+        fence();
+        const hash = fingerprintWorkSessionRequest(request);
+        let configuredFields;
+        let entry = journal.read().operations.find((operation) => operation.request.requestId === request.requestId);
+        if (entry && entry.fingerprint !== hash)
+            throw new Error('Managed-session request changed during recovery.');
+        if (!entry) {
+            entry = { request, fingerprint: hash, phase: 'configuring',
+                ...(replayed ? { completion: { status: 'uncertain', error: { code: 'local_state_missing',
+                            message: 'The host lost the saved setup result. Inspect this local runtime before trying again.' } }, phase: 'complete' } : {}),
+            };
+            await journal.mutate((state) => { state.operations.push(entry); });
+        }
+        if (!entry.completion) {
+            if (request.selection.mode !== 'configure') {
+                entry.completion = { status: 'failed', error: { code: 'unsupported_setup', message: 'This host only supports managed setup.' } };
+            }
+            else {
+                try {
+                    const result = await options.configure(request);
+                    fence();
+                    entry.completion = { status: 'configured', settings: result.settings };
+                    configuredFields = result.fields;
+                    await journal.mutate((state) => {
+                        const saved = state.operations.find((operation) => operation.request.requestId === request.requestId);
+                        saved.phase = 'complete';
+                        saved.completion = entry.completion;
+                    });
+                }
+                catch (error) {
+                    reportError(error, 'configure');
+                    entry.completion = { status: 'failed', error: { code: 'managed_configuration_failed',
+                            message: (error instanceof Error ? error.message : String(error)).slice(0, 512) } };
+                }
+            }
+            if (entry.completion.status !== 'configured') {
+                await journal.mutate((state) => {
+                    const saved = state.operations.find((operation) => operation.request.requestId === request.requestId);
+                    saved.phase = 'complete';
+                    saved.completion = entry.completion;
+                });
+            }
+        }
+        fence();
+        const completed = await authority.acknowledge(journal, request.requestId, entry.completion);
+        if (completed.binding) {
+            broker.bindings = [...broker.bindings.filter((binding) => binding.conversationId !== completed.conversationId), completed.binding];
+        }
+        if (configuredFields && completed.status === 'configured') {
+            await report(request.conversationId, configuredFields).catch((error) => reportError(error, 'report-configured'));
+        }
+    }
+    async function doReconcile() {
+        fence();
+        const outstanding = journal.read().operations.find((entry) => !entry.acknowledged && !entry.quarantined);
+        let claimed;
+        try {
+            claimed = await authority.claim(outstanding?.request.requestId);
+        }
+        catch (error) {
+            if (outstanding && error instanceof CanonApiError && error.code === 'WORK_SESSION_MEMBERSHIP_REQUIRED') {
+                await journal.mutate((state) => {
+                    state.operations.find((entry) => entry.request.requestId === outstanding.request.requestId).quarantined = 'Conversation membership was removed.';
+                });
+                return;
+            }
+            throw error;
+        }
+        fence();
+        if (!claimed.request) {
+            if (outstanding)
+                await journal.mutate((state) => {
+                    state.operations.find((entry) => entry.request.requestId === outstanding.request.requestId).quarantined = 'Request no longer belongs to this runtime.';
+                });
+            return;
+        }
+        if (['configured', 'failed', 'expired'].includes(claimed.request.status)) {
+            if (outstanding)
+                await journal.mutate((state) => {
+                    state.operations.find((entry) => entry.request.requestId === outstanding.request.requestId).acknowledged = true;
+                });
+            if (claimed.request.binding) {
+                broker.bindings = [...broker.bindings.filter((binding) => binding.conversationId !== claimed.request.conversationId), claimed.request.binding];
+            }
+            return;
+        }
+        await processRequest(claimed.request, claimed.replayed);
+    }
+    function reconcile() {
+        if (stopped || !started)
+            return Promise.resolve();
+        processing ??= doReconcile().finally(() => { processing = undefined; });
+        return processing;
+    }
+    async function renew() {
+        fence();
+        const state = await authority.heartbeat(await options.catalog());
+        if (!stopped)
+            retain(state);
+    }
+    function start() {
+        if (stopped)
+            throw new Error('Managed-session host already stopped.');
+        if (started && broker && broker.lease.expiresAt - Date.now() >= 5_000)
+            return Promise.resolve();
+        starting ??= (async () => {
+            if (!started)
+                await journal.load();
+            retain(await authority.register(await options.catalog()));
+            if (stopped)
+                return;
+            if (!started) {
+                started = true;
+                heartbeatTimer = setInterval(() => {
+                    if (!renewing)
+                        renewing = renew().catch((error) => reportError(error, 'lease-renewal')).finally(() => { renewing = undefined; });
+                }, heartbeatMs);
+                heartbeatTimer.unref?.();
+                pollTimer = setInterval(() => { void reconcile().catch((error) => reportError(error, 'request')); }, pollMs);
+                pollTimer.unref?.();
+            }
+            await reconcile();
+        })().finally(() => { starting = undefined; });
+        return starting;
+    }
+    async function report(conversationId, fields, setupState) {
+        fence();
+        const binding = broker.bindings.find((entry) => entry.conversationId === conversationId);
+        await options.client.reportWorkSessionDetails({ ...auth(), conversationId,
+            ...(binding ? { workSessionId: binding.workSessionId } : {}),
+            ...(setupState ? { setupState } : binding ? { setupState: binding.kind === 'managed' ? 'configured' : 'attached' } : {}),
+            fields });
+    }
+    async function stop() {
+        if (stopped)
+            return;
+        stopped = true;
+        if (pollTimer)
+            clearInterval(pollTimer);
+        if (heartbeatTimer)
+            clearInterval(heartbeatTimer);
+        await Promise.allSettled([starting, processing, renewing].filter(Boolean));
+        try {
+            if (broker)
+                await options.client.releaseWorkSessionRuntime(auth());
+        }
+        catch (error) {
+            reportError(error, 'release-runtime');
+        }
+        await journal.close();
+    }
+    function binding(conversationId) {
+        if (stopped || !broker || broker.lease.expiresAt - Date.now() < 5_000)
+            return undefined;
+        return broker.bindings.find((entry) => entry.conversationId === conversationId && entry.kind === 'managed');
+    }
+    return { start, stop, reconcile, report, binding };
+}

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

@@ -0,0 +1,21 @@
+import { CanonClient, type WorkSessionCatalog, type WorkSessionCompletion, type WorkSessionRequest, type WorkSessionRuntimeAuth, type WorkSessionRuntimeState } from '@canonmsg/core';
+import type { WorkSessionJournal } from './work-session-state.js';
+/** The same request identity is used by native creation and managed setup recovery. */
+export declare function fingerprintWorkSessionRequest(request: WorkSessionRequest): string;
+/** Shared broker authority; each host retains its own delivery and request dispatch loop. */
+export declare function createWorkSessionAuthority(options: {
+    client: CanonClient;
+    hostId: string;
+    runtimeEpoch: string;
+    displayName: string;
+    isStopped(): boolean;
+}): {
+    auth: () => WorkSessionRuntimeAuth;
+    fence: () => void;
+    retain: (state: WorkSessionRuntimeState) => WorkSessionRuntimeState;
+    register: (catalog: WorkSessionCatalog) => Promise<WorkSessionRuntimeState>;
+    heartbeat: (catalog: WorkSessionCatalog) => Promise<WorkSessionRuntimeState>;
+    claim: (requestId?: string) => Promise<import("@canonmsg/backend-contracts").WorkSessionClaimResult>;
+    acknowledge: (journal: WorkSessionJournal, requestId: string, result: WorkSessionCompletion) => Promise<WorkSessionRequest>;
+    state: () => WorkSessionRuntimeState | undefined;
+};

package/dist/work-session-coordination.js

@@ -0,0 +1,53 @@
+import { createHash } from 'node:crypto';
+/** The same request identity is used by native creation and managed setup recovery. */
+export function fingerprintWorkSessionRequest(request) {
+    return createHash('sha256').update(JSON.stringify([
+        request.agentId, request.conversationId, request.requestId, request.hostId,
+        request.runtimeEpoch, request.catalogRevision, request.selection, request.requestedBy,
+    ])).digest('hex');
+}
+/** Shared broker authority; each host retains its own delivery and request dispatch loop. */
+export function createWorkSessionAuthority(options) {
+    let current;
+    function auth() {
+        if (!current)
+            throw new Error('Work-session runtime is not registered.');
+        return { hostId: options.hostId, runtimeEpoch: options.runtimeEpoch,
+            leaseToken: current.lease.leaseToken };
+    }
+    function fence() {
+        if (options.isStopped() || !current || current.lease.expiresAt - Date.now() < 5_000)
+            throw new Error('Work-session runtime no longer has a fresh lease.');
+    }
+    function retain(state) {
+        if (state.lease.hostId !== options.hostId || state.lease.runtimeEpoch !== options.runtimeEpoch
+            || (current && current.ownerId !== state.ownerId))
+            throw new Error('Work-session runtime identity changed.');
+        current = state;
+        return state;
+    }
+    async function register(catalog) {
+        return retain(await options.client.registerWorkSessionRuntime({ hostId: options.hostId,
+            runtimeEpoch: options.runtimeEpoch, displayName: options.displayName, catalog }));
+    }
+    async function heartbeat(catalog) {
+        fence();
+        return retain(await options.client.heartbeatWorkSessionRuntime({ ...auth(), catalog }));
+    }
+    function claim(requestId) {
+        fence();
+        return options.client.claimWorkSessionRequest({ ...auth(), ...(requestId ? { requestId } : {}) });
+    }
+    async function acknowledge(journal, requestId, result) {
+        fence();
+        const completed = await options.client.completeWorkSessionRequest({ ...auth(), requestId, result });
+        if (completed.status !== result.status)
+            throw new Error('Canon did not acknowledge the requested work-session outcome.');
+        await journal.mutate((state) => {
+            state.operations.find((entry) => entry.request.requestId === requestId).acknowledged = true;
+        });
+        return completed;
+    }
+    return { auth, fence, retain, register, heartbeat, claim, acknowledge,
+        state: () => current };
+}

package/dist/work-session-host.js

@@ -1,8 +1,9 @@
-import { createHash, randomUUID } from 'node:crypto';
+import { 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';
+import { createWorkSessionAuthority, fingerprintWorkSessionRequest } from './work-session-coordination.js';
 /** One authenticated transport and liveness publisher, with durable per-room native routes. */
 export function createCanonWorkSessionHost(options) {
     const connection = { ...options.connection };
@@ -32,6 +33,8 @@ export function createCanonWorkSessionHost(options) {
     let connected = false;
     let agentContext;
     let stopped = false;
+    const authority = createWorkSessionAuthority({ client, hostId: options.hostId,
+        runtimeEpoch, displayName: options.displayName, isStopped: () => stopped });
     let startPromise;
     let stopPromise;
     let cleanupPromise;
@@ -40,6 +43,8 @@ export function createCanonWorkSessionHost(options) {
     let expiryTimer;
     let processing;
     let renewing;
+    let reporting;
+    let reportsRequested = false;
     let rejectConnection;
     let resolveConnection;
     const report = (error, operation) => { try {
@@ -54,20 +59,10 @@ export function createCanonWorkSessionHost(options) {
             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.');
-    }
+    const auth = authority.auth;
+    const fence = authority.fence;
     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;
+        broker = authority.retain(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));
@@ -122,9 +117,45 @@ export function createCanonWorkSessionHost(options) {
         room.activate();
         room.session.refreshRuntimeState();
         updatePresence();
+        scheduleReports();
+    }
+    async function reportRoom(room) {
+        if (!room.acknowledged || room.stopped || !options.provider.describe)
+            return;
+        fence();
+        const fields = await options.provider.describe(room.binding.nativeSessionId, room.binding.settings);
+        if (stopped || rooms.get(room.binding.conversationId) !== room || room.stopped || !room.acknowledged)
+            return;
+        fence();
+        await client.reportWorkSessionDetails({ ...auth(), conversationId: room.binding.conversationId,
+            workSessionId: room.binding.workSessionId, setupState: 'attached', fields });
+    }
+    function scheduleReports() {
+        if (stopped || !options.provider.describe)
+            return;
+        reportsRequested = true;
+        if (reporting)
+            return;
+        reporting = Promise.resolve().then(async () => {
+            while (reportsRequested && !stopped) {
+                reportsRequested = false;
+                const active = [...rooms.values()].filter((room) => room.acknowledged && !room.stopped);
+                const outcomes = await Promise.allSettled(active.map(reportRoom));
+                for (const outcome of outcomes) {
+                    if (outcome.status === 'rejected')
+                        report(outcome.reason, 'session-details');
+                }
+            }
+        }).catch((error) => report(error, 'session-details')).finally(() => {
+            reporting = undefined;
+            if (reportsRequested && !stopped)
+                scheduleReports();
+        });
     }
     async function attach(binding, confirmed = false) {
         fence();
+        if (typeof binding.nativeSessionId !== 'string')
+            throw new Error('This host cannot attach a managed-session binding.');
         const existing = rooms.get(binding.conversationId);
         if (existing && existing.binding.nativeSessionId === binding.nativeSessionId && !existing.stopped) {
             if (confirmed)
@@ -194,7 +225,7 @@ export function createCanonWorkSessionHost(options) {
                     updatePresence();
                 },
             });
-            rooms.set(binding.conversationId, { binding, session, controller, releaseNative, stopped: false, acknowledged: confirmed, activate: activateRoute });
+            rooms.set(binding.conversationId, { binding: binding, session, controller, releaseNative, stopped: false, acknowledged: confirmed, activate: activateRoute });
             if (confirmed)
                 activateRoute();
             await session.start();
@@ -219,16 +250,12 @@ export function createCanonWorkSessionHost(options) {
             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);
+        const hash = fingerprintWorkSessionRequest(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.');
@@ -313,12 +340,7 @@ export function createCanonWorkSessionHost(options) {
             }
         }
         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; });
+            const completed = await authority.acknowledge(journal, request.requestId, operation.completion);
             if (completed.status === 'attached')
                 activate(request.conversationId);
         }
@@ -343,7 +365,7 @@ export function createCanonWorkSessionHost(options) {
         const outstanding = journal.read().operations.find((entry) => !entry.acknowledged && !entry.quarantined);
         let claimed;
         try {
-            claimed = await client.claimWorkSessionRequest({ ...auth(), ...(outstanding ? { requestId: outstanding.request.requestId } : {}) });
+            claimed = await authority.claim(outstanding?.request.requestId);
         }
         catch (error) {
             if (outstanding && error instanceof CanonApiError && error.code === 'WORK_SESSION_MEMBERSHIP_REQUIRED') {
@@ -360,7 +382,7 @@ export function createCanonWorkSessionHost(options) {
                 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 (['attached', 'configured', 'failed', 'expired'].includes(claimed.request.status)) {
             if (outstanding) {
                 if (claimed.request.status === 'attached' && claimed.request.binding) {
                     try {
@@ -417,9 +439,10 @@ export function createCanonWorkSessionHost(options) {
         // 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 });
+        const state = await authority.heartbeat(catalog);
         if (!stopped)
             retainLease(state);
+        scheduleReports();
     }
     function start() {
         if (stopped)
@@ -435,7 +458,7 @@ export function createCanonWorkSessionHost(options) {
             const catalog = await options.provider.catalog();
             if (stopped)
                 return;
-            retainLease(await client.registerWorkSessionRuntime({ hostId: options.hostId, runtimeEpoch, displayName: options.displayName, catalog }));
+            retainLease(await authority.register(catalog));
             if (stopped) {
                 fenceShutdown();
                 return;

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

@@ -2,7 +2,7 @@ import { type ExclusiveJsonFileStore, type NativeSessionInteractionResult, type
 export interface WorkSessionOperation {
     request: WorkSessionRequest;
     fingerprint: string;
-    phase: 'creating' | 'created' | 'attaching' | 'complete';
+    phase: 'configuring' | 'creating' | 'created' | 'attaching' | 'complete';
     nativeSessionId?: string;
     settings?: WorkSessionSettings;
     completion?: WorkSessionCompletion;

package/dist/work-session-state.js

@@ -16,7 +16,7 @@ export function createWorkSessionJournal(store, identity) {
                     || loaded.hostId !== identity.hostId || !Array.isArray(loaded.operations)
                     || !Array.isArray(loaded.interactions)
                     || loaded.operations.some((entry) => !entry?.request?.requestId || !entry.fingerprint
-                        || !['creating', 'created', 'attaching', 'complete'].includes(entry.phase)
+                        || !['configuring', 'creating', 'created', 'attaching', 'complete'].includes(entry.phase)
                         || (entry.phase === 'complete' && !entry.completion))
                     || loaded.interactions.some((entry) => !entry?.id || !entry.fingerprint || !Number.isFinite(entry.expiresAt))) {
                     throw new Error('Work-session journal cannot be verified; retain it for recovery.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/agent-sdk",
-  "version": "11.0.3",
+  "version": "11.1.1",
   "description": "Canon Agent SDK — build AI agents that participate in Canon conversations",
   "type": "module",
   "main": "dist/index.js",
@@ -28,7 +28,7 @@
     "node": ">=22.22.3"
   },
   "dependencies": {
-    "@canonmsg/core": "^13.0.6"
+    "@canonmsg/core": "^13.2.0"
   },
   "repository": {
     "type": "git",