@canonmsg/agent-sdk 4.0.0 → 5.1.0

package/dist/canon-agent.js

@@ -0,0 +1,1992 @@
+import { ApprovalManager, RuntimeRequestManager, runtimeInputDescriptor, runtimeCardDescriptor, CanonClient, ControlChannelPoller, buildCanonTurnContextV2, buildCanonGroupContext, buildParticipationHistorySnapshot, createTurnOutputController, createRuntimeStatePublisher, createTypingStatusPublisher, diffCanonMemberIds, FINAL_MESSAGE_HANDOFF_MS, RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildRuntimeCardOutcome, buildRuntimeInputOutcome, initRTDBAuth, normalizeRuntimeCommandDescriptors, normalizeTurnMetadata, reachOutToCanonContact, resolveCanonReplyContext, resolveMessageActiveSelfContextId, resolveRuntimeProvenance, selectActiveSelfContexts, renderCanonHostInboundContent, sendMessageWithRetry, } from '@canonmsg/core';
+import { createHash, randomUUID } from 'node:crypto';
+import { AuthManager } from './auth.js';
+import { Debouncer } from './debouncer.js';
+import { buildRuntimeCardCreateArgs } from './runtime-card.js';
+import { materializeMessageMedia, materializeReplyContextMedia, sendMediaFileMessage, uploadMediaFile, } from './media.js';
+import { SessionManager } from './session-manager.js';
+const AGENT_RUNTIME_HEARTBEAT_MS = 30_000;
+const RUNTIME_CONTROL_POLL_INTERVAL_MS = 2_000;
+const RUNTIME_PRIMITIVE_DEDUPE_TTL_MS = 5 * 60 * 1000;
+const RUNTIME_PRIMITIVE_DEDUPE_MAX = 1_000;
+const DEFAULT_RUNTIME_INPUT_TIMEOUT_MS = 5 * 60_000;
+const RUNTIME_INPUT_ID_PATTERN = /^[A-Za-z0-9_.:-]{1,160}$/;
+const SDK_MESSAGE_ID_READABLE_MAX = 120;
+const SDK_RUNTIME_CAPABILITIES = {
+    supportsInterrupt: false,
+    supportsInputInterrupt: false,
+    supportsQueue: true,
+    supportsInterleave: false,
+    supportsRequiresAction: true,
+    supportsNonFinalPermanentMessages: false,
+};
+const DEFAULT_SDK_RUNTIME_DESCRIPTOR = {
+    coreControls: [],
+    runtimeControls: [],
+    supportsInterrupt: false,
+    streamingTextMode: 'snapshot',
+    runtimeCards: {
+        rich: {
+            schema: 'canon.card.v1',
+            lifecycle: 'blocking_requires_action',
+            responder: 'agent_owner',
+            result: 'action_or_values',
+            maxTimeoutMs: 30 * 60_000,
+            blockKinds: ['summary', 'metricGrid', 'chart', 'table', 'list', 'callout', 'actions', 'mediaPreview', 'details'],
+            actionFieldTypes: ['text', 'textarea', 'select', 'multiSelect', 'boolean', 'date', 'number', 'currency', 'searchSelect', 'lineItems'],
+            native: true,
+        },
+    },
+};
+const STANDARD_PRIMITIVE_COMMANDS = {
+    'runtime.status': {
+        id: 'runtime-status',
+        label: 'Runtime status',
+        description: 'Ask the runtime for its current status.',
+        primitive: 'runtime.status',
+        aliases: ['status'],
+        category: 'runtime',
+        placements: ['composer_slash', 'command_palette'],
+        availability: ['always'],
+        dispatch: { kind: 'primitive', primitive: 'runtime.status' },
+    },
+    'runtime.reasoning.set': {
+        id: 'thinking-level',
+        label: 'Thinking level',
+        description: 'Set the runtime reasoning or effort level.',
+        primitive: 'runtime.reasoning.set',
+        aliases: ['think', 'effort'],
+        category: 'runtime',
+        placements: ['composer_slash', 'command_palette'],
+        availability: ['always'],
+        args: [{
+                id: 'level',
+                label: 'Level',
+                kind: 'enum',
+                required: true,
+                choices: [
+                    { value: 'low', label: 'Low' },
+                    { value: 'medium', label: 'Medium' },
+                    { value: 'high', label: 'High' },
+                ],
+            }],
+        dispatch: { kind: 'primitive', primitive: 'runtime.reasoning.set' },
+    },
+    'runtime.verbosity.set': {
+        id: 'verbosity',
+        label: 'Verbosity',
+        description: 'Set runtime verbosity.',
+        primitive: 'runtime.verbosity.set',
+        aliases: ['verbose'],
+        category: 'runtime',
+        placements: ['composer_slash', 'command_palette'],
+        availability: ['always'],
+        args: [{
+                id: 'level',
+                label: 'Level',
+                kind: 'enum',
+                required: true,
+                choices: [
+                    { value: 'off', label: 'Off' },
+                    { value: 'on', label: 'On' },
+                    { value: 'full', label: 'Full' },
+                ],
+            }],
+        dispatch: { kind: 'primitive', primitive: 'runtime.verbosity.set' },
+    },
+    'runtime.usage': {
+        id: 'usage',
+        label: 'Usage',
+        description: 'Show or change runtime usage reporting.',
+        primitive: 'runtime.usage',
+        aliases: ['usage'],
+        category: 'runtime',
+        placements: ['composer_slash', 'command_palette'],
+        availability: ['always'],
+        dispatch: { kind: 'primitive', primitive: 'runtime.usage' },
+    },
+    'context.compact': {
+        id: 'compact-context',
+        label: 'Compact context',
+        description: 'Ask the runtime to compact its conversation context.',
+        primitive: 'context.compact',
+        aliases: ['compact'],
+        category: 'session',
+        placements: ['composer_slash', 'command_palette'],
+        availability: ['always'],
+        dispatch: { kind: 'primitive', primitive: 'context.compact' },
+    },
+    'session.new': {
+        id: 'new-session-primitive',
+        label: 'New session',
+        description: 'Ask the runtime to start a fresh session.',
+        primitive: 'session.new',
+        aliases: ['new'],
+        category: 'session',
+        placements: ['composer_slash', 'command_palette', 'session_strip'],
+        availability: ['always'],
+        dispatch: { kind: 'primitive', primitive: 'session.new' },
+    },
+    'session.reset': {
+        id: 'reset-session',
+        label: 'Reset session',
+        description: 'Ask the runtime to reset the current session.',
+        primitive: 'session.reset',
+        aliases: ['reset'],
+        category: 'session',
+        placements: ['composer_slash', 'command_palette'],
+        availability: ['always'],
+        dispatch: { kind: 'primitive', primitive: 'session.reset' },
+    },
+};
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function sleepWithAbort(ms, signal) {
+    if (signal.aborted)
+        return Promise.reject(createTurnAbortError());
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(resolve, ms);
+        signal.addEventListener('abort', () => {
+            clearTimeout(timer);
+            reject(createTurnAbortError());
+        }, { once: true });
+    });
+}
+function safeRuntimeInputId(value, kind) {
+    const raw = value?.trim() || `${kind}_${randomUUID()}`;
+    const normalized = raw.replace(/[.#$\[\]\/\s]+/g, '_').slice(0, 160);
+    return RUNTIME_INPUT_ID_PATTERN.test(normalized)
+        ? normalized
+        : `${kind}_${randomUUID()}`;
+}
+function safeRuntimeCardId(value) {
+    const raw = value?.trim() || `card_${randomUUID()}`;
+    const normalized = raw.replace(/[.#$\[\]\/\s]+/g, '_').slice(0, 80);
+    return RUNTIME_INPUT_ID_PATTERN.test(normalized)
+        ? normalized
+        : `card_${randomUUID()}`;
+}
+function buildSdkMessageId(parts) {
+    const raw = parts
+        .map((part) => part == null ? '' : String(part))
+        .filter(Boolean)
+        .join(':');
+    const hash = createHash('sha256').update(raw || 'sdk-message').digest('hex').slice(0, 16);
+    const readable = (raw || 'sdk-message')
+        .replace(/[^A-Za-z0-9_.:-]+/g, '_')
+        .replace(/_+/g, '_')
+        .replace(/^[:_.-]+|[:_.-]+$/g, '')
+        .slice(0, SDK_MESSAGE_ID_READABLE_MAX);
+    return `${readable || 'sdk-message'}:${hash}`;
+}
+function isRuntimePrimitiveId(value) {
+    return value === 'runtime.status'
+        || value === 'runtime.reasoning.set'
+        || value === 'runtime.verbosity.set'
+        || value === 'runtime.usage'
+        || value === 'context.compact'
+        || value === 'session.new'
+        || value === 'session.reset';
+}
+function normalizePrimitiveArgs(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return {};
+    }
+    const args = {};
+    for (const [key, rawValue] of Object.entries(value)) {
+        if (!/^[A-Za-z0-9_-]+$/.test(key))
+            continue;
+        if (typeof rawValue === 'boolean' || typeof rawValue === 'string') {
+            args[key] = rawValue;
+        }
+    }
+    return args;
+}
+function normalizeRuntimeFact(fact) {
+    const id = fact.id.trim();
+    const label = fact.label.trim();
+    const value = fact.value.trim();
+    if (!id || !label || !value)
+        return null;
+    return {
+        ...fact,
+        id,
+        label,
+        value,
+    };
+}
+function normalizeRuntimeActivityItem(item) {
+    return {
+        ...item,
+        id: item.id.trim(),
+        title: item.title.trim() || item.kind,
+        updatedAt: item.updatedAt || Date.now(),
+    };
+}
+function createTurnAbortError() {
+    const error = new Error('Canon turn was interrupted before reply delivery.');
+    error.name = 'AbortError';
+    return error;
+}
+function isAbortLikeError(error) {
+    if (!error || typeof error !== 'object')
+        return false;
+    const record = error;
+    if (record.name === 'AbortError' || record.code === 'ABORT_ERR')
+        return true;
+    return typeof record.message === 'string' && /\babort(?:ed)?\b/i.test(record.message);
+}
+export class CanonAgent {
+    options;
+    apiClient;
+    authManager;
+    debouncer;
+    realtimeManager = null;
+    sessionManager = null;
+    handler = null;
+    contactRequestHandler = null;
+    contactApprovedHandler = null;
+    contactAddedHandler = null;
+    contactRemovedHandler = null;
+    messageUpdatedHandler = null;
+    interruptHandler = null;
+    stopAndDropHandler = null;
+    newSessionHandler = null;
+    primitiveHandlers = new Map();
+    primitiveFallbackHandler = null;
+    /** Contact-graph operations (`agent.contacts.*`). Initialized in the constructor. */
+    contacts;
+    /** Block/unblock operations (`agent.users.*`). Initialized in the constructor. */
+    users;
+    /** Conversation discovery for choosing existing sessions intentionally. */
+    conversations;
+    reachOutInFlight = new Map();
+    agentId = null;
+    agentContext = null;
+    approvalManager = null;
+    approvalManagerAgentId = null;
+    approvalManagerOwnerId = null;
+    /**
+     * Shared poll/timeout/abort engine for interactive runtime input + card
+     * requests. The server request is still created inline (host-specific
+     * `native`/`responseUserId`), so the descriptors register a no-op `create`
+     * but keep the built-in `cancel`: passing the turn's abort `signal` lets the
+     * manager fire `consume({ cancel: true })` on interrupt, so the hosts no
+     * longer hand-roll a `cancelPendingRequest`.
+     */
+    runtimeRequestManager = null;
+    cachedConversationIds = [];
+    running = false;
+    runtimeHeartbeatTimer = null;
+    rtdbHandle = null;
+    controlPoller = null;
+    activeAbortControllers = new Map();
+    activeTurns = new Map();
+    conversationMemberIds = new Map();
+    pendingMembershipChanges = new Map();
+    typingSignals;
+    sseConnectedLogged = false;
+    constructor(options) {
+        this.options = {
+            baseUrl: 'https://api-6m6mlelskq-uc.a.run.app',
+            deliveryMode: 'auto',
+            debounceMs: 2000,
+            historyLimit: 50,
+            autoMarkRead: true,
+            runtimeControlSurface: 'agent',
+            ...options,
+        };
+        this.apiClient = new CanonClient(this.options.apiKey, this.options.baseUrl);
+        this.typingSignals = createTypingStatusPublisher({
+            setTyping: (conversationId, typing, status) => status
+                ? this.apiClient.setTyping(conversationId, typing, status)
+                : this.apiClient.setTyping(conversationId, typing),
+        });
+        this.authManager = new AuthManager(this.apiClient);
+        this.debouncer = new Debouncer(this.options.debounceMs);
+        const apiClient = this.apiClient;
+        this.contacts = {
+            list: () => apiClient.listContacts(),
+            get: (contactId) => apiClient.getContact(contactId),
+            remove: (contactId) => apiClient.deleteContact(contactId),
+            request: (targetUserId, message) => apiClient.createContactRequest(targetUserId, message ?? null),
+        };
+        this.users = {
+            block: (userId) => apiClient.blockUser(userId),
+            unblock: (userId) => apiClient.unblockUser(userId),
+        };
+        this.conversations = {
+            list: async (options = {}) => {
+                const conversations = await apiClient.getConversations();
+                if (!options.targetUserId)
+                    return conversations;
+                return conversations.filter((conversation) => conversation.memberIds.includes(options.targetUserId));
+            },
+        };
+        if (options.sessions?.enabled) {
+            this.sessionManager = new SessionManager({
+                contextLimit: options.sessions.contextLimit,
+                concurrency: options.sessions.concurrency,
+                idleTimeoutMs: options.sessions.idleTimeoutMs,
+            });
+        }
+        this.interruptHandler = options.runtimeControls?.onInterrupt ?? null;
+        this.stopAndDropHandler = options.runtimeControls?.onStopAndDrop ?? null;
+        this.newSessionHandler = options.runtimeControls?.onNewSession ?? null;
+        for (const [primitive, handler] of Object.entries(options.runtimePrimitives ?? {})) {
+            if (primitive === '*') {
+                this.primitiveFallbackHandler = handler;
+            }
+            else if (isRuntimePrimitiveId(primitive)) {
+                this.primitiveHandlers.set(primitive, handler);
+            }
+        }
+    }
+    ensureApprovalManager(agentContext = this.agentContext) {
+        const agentId = agentContext?.agentId || this.agentId;
+        const ownerId = agentContext?.ownerId;
+        if (!agentId || !ownerId)
+            return null;
+        if (this.approvalManager
+            && this.approvalManagerAgentId === agentId
+            && this.approvalManagerOwnerId === ownerId) {
+            return this.approvalManager;
+        }
+        if (this.approvalManager?.pendingCount) {
+            return this.approvalManager;
+        }
+        this.approvalManager?.dispose();
+        this.approvalManager = new ApprovalManager(this.apiClient, agentId, ownerId);
+        this.approvalManagerAgentId = agentId;
+        this.approvalManagerOwnerId = ownerId;
+        return this.approvalManager;
+    }
+    /**
+     * Shared engine for interactive runtime input + card polling. Unlike approval,
+     * these families do not need an owner (the request is created inline with the
+     * caller's own `responseUserId` policy), so the manager is always available.
+     * The registered descriptors keep the built-in poll/consume/timeout logic and
+     * the built-in `cancel` (best-effort `consume({ cancel: true })`), replacing
+     * only `create` with a no-op because the request is already created inline.
+     * On abort the manager runs that cancel via the passed `signal`.
+     */
+    ensureRuntimeRequestManager() {
+        if (!this.runtimeRequestManager) {
+            const manager = new RuntimeRequestManager(this.apiClient, {
+                agentId: this.agentId ?? '',
+                ownerId: '',
+            });
+            manager.register('input', {
+                ...runtimeInputDescriptor,
+                create: async ({ requestId }) => ({ requestId }),
+            });
+            manager.register('card', {
+                ...runtimeCardDescriptor,
+                create: async ({ requestId }) => ({ requestId }),
+            });
+            this.runtimeRequestManager = manager;
+        }
+        return this.runtimeRequestManager;
+    }
+    filterApprovalReplyMessages(conversationId, messages) {
+        const manager = this.ensureApprovalManager();
+        if (!manager) {
+            return messages.filter((message) => {
+                const metadata = message.metadata;
+                return !(metadata && typeof metadata === 'object' && !Array.isArray(metadata)
+                    && metadata.type === 'approval_reply');
+            });
+        }
+        return messages.filter((message) => {
+            const metadata = message.metadata;
+            const metadataRecord = metadata && typeof metadata === 'object' && !Array.isArray(metadata)
+                ? metadata
+                : null;
+            const consumed = manager.handleMessage(conversationId, {
+                senderId: message.senderId,
+                ...(metadataRecord ? { metadata: metadataRecord } : {}),
+            });
+            return !consumed && metadataRecord?.type !== 'approval_reply';
+        });
+    }
+    on(event, handler) {
+        if (event === 'message') {
+            this.handler = handler;
+            return;
+        }
+        if (event === 'messageUpdated') {
+            this.messageUpdatedHandler = handler;
+            return;
+        }
+        if (event === 'contactRequest') {
+            this.contactRequestHandler = handler;
+            return;
+        }
+        if (event === 'contactApproved') {
+            this.contactApprovedHandler = handler;
+            return;
+        }
+        if (event === 'contactAdded') {
+            this.contactAddedHandler = handler;
+            return;
+        }
+        if (event === 'interrupt') {
+            this.interruptHandler = handler;
+            if (this.running) {
+                void this.baselineRuntimeControlSignals(this.cachedConversationIds)
+                    .then(() => this.startRuntimeControlPolling())
+                    .catch(() => { });
+            }
+            void this.publishAgentRuntime().catch(() => { });
+            return;
+        }
+        if (event === 'stopAndDrop') {
+            this.stopAndDropHandler = handler;
+            if (this.running) {
+                void this.baselineRuntimeControlSignals(this.cachedConversationIds)
+                    .then(() => this.startRuntimeControlPolling())
+                    .catch(() => { });
+            }
+            void this.publishAgentRuntime().catch(() => { });
+            return;
+        }
+        if (event === 'newSession') {
+            this.newSessionHandler = handler;
+            if (this.running) {
+                void this.baselineRuntimeControlSignals(this.cachedConversationIds)
+                    .then(() => this.startRuntimeControlPolling())
+                    .catch(() => { });
+            }
+            void this.publishAgentRuntime().catch(() => { });
+            return;
+        }
+        this.contactRemovedHandler = handler;
+    }
+    onPrimitive(primitive, handler) {
+        if (primitive === '*') {
+            this.primitiveFallbackHandler = handler;
+        }
+        else {
+            this.primitiveHandlers.set(primitive, handler);
+        }
+        if (this.running) {
+            this.startRuntimeControlPolling();
+        }
+        void this.publishAgentRuntime().catch(() => { });
+    }
+    describeCommands(_provider) {
+        return this.buildRuntimeDescriptor().commands ?? [];
+    }
+    async publishRuntimeFacts(conversationId, facts) {
+        this.rememberConversationId(conversationId);
+        const publisher = this.requireRuntimeStatePublisher();
+        const normalizedFacts = facts
+            .map(normalizeRuntimeFact)
+            .filter((fact) => Boolean(fact));
+        await publisher.patchRuntimeInfo(conversationId, {
+            descriptor: this.buildRuntimeDescriptor(),
+            facts: normalizedFacts,
+        });
+    }
+    async publishRuntimeActivity(conversationId, item) {
+        this.rememberConversationId(conversationId);
+        const normalized = normalizeRuntimeActivityItem(item);
+        if (!normalized.id) {
+            throw new Error('Runtime activity item id is required.');
+        }
+        await this.requireRuntimeStatePublisher().writeRuntimeActivity(conversationId, normalized);
+    }
+    async clearRuntimeActivity(conversationId, options) {
+        this.rememberConversationId(conversationId);
+        await this.requireRuntimeStatePublisher().clearRuntimeActivity(conversationId, options);
+    }
+    /**
+     * Resolve admission live for a target user (typically read off a shared
+     * contact card) and route into either an immediate message or a contact
+     * request. Never reads `card.accessLevel` — that snapshot is stale by the
+     * time an LLM acts on it. Instead defers to `resolveAdmission` so the
+     * answer reflects the target's *current* inbound policy.
+     */
+    async reachOut(card, options) {
+        const target = {
+            targetUserId: card.userId,
+            ...(card.userType === 'ai_agent' && card.canonContactId
+                ? { canonContactId: card.canonContactId }
+                : {}),
+        };
+        const targetKey = target.canonContactId ?? target.targetUserId;
+        // Include the opener/request payloads in the dedupe key so two concurrent
+        // calls with different `text`, `requestMessage`, or setup choices don't silently collapse
+        // and lose the second caller's intended side effect.
+        const contextualKey = options?.selfContext
+            ? `${options.sourceConversationId ?? ''}\u0000${options.selfContext.type}\u0000${options.selfContext.context}`
+            : '';
+        const inFlightKey = `${targetKey}\u0000${options?.text ?? ''}\u0000${options?.requestMessage ?? ''}\u0000${JSON.stringify(options?.sessionConfig ?? null)}\u0000${JSON.stringify(options?.sessionSelection ?? null)}\u0000${contextualKey}`;
+        const inFlight = this.reachOutInFlight.get(inFlightKey);
+        if (inFlight)
+            return inFlight;
+        const promise = this.executeReachOut(target, options).finally(() => {
+            this.reachOutInFlight.delete(inFlightKey);
+        });
+        this.reachOutInFlight.set(inFlightKey, promise);
+        return promise;
+    }
+    async executeReachOut(target, options) {
+        const { targetUserId } = target;
+        if (options?.selfContext) {
+            if (!options.sourceConversationId) {
+                throw new Error('sourceConversationId is required for contextual reachOut');
+            }
+            if (!options.text) {
+                throw new Error('text is required for contextual reachOut');
+            }
+            const result = await this.apiClient.sendContextualMessage({
+                sourceConversationId: options.sourceConversationId,
+                targetUserId,
+                text: options.text,
+                selfContext: options.selfContext,
+                requestMessage: options.requestMessage ?? null,
+                sessionConfig: options.sessionConfig ?? null,
+                sessionSelection: options.sessionSelection,
+            });
+            return result.status === 'messaged'
+                ? {
+                    status: 'messaged',
+                    conversationId: result.conversationId,
+                    messageId: result.messageId,
+                    selfContextId: result.selfContextId,
+                    created: result.created,
+                    reused: result.reused,
+                    sessionSelection: result.sessionSelection,
+                }
+                : result;
+        }
+        return reachOutToCanonContact(this.apiClient, {
+            ...(target.canonContactId
+                ? { canonContactId: target.canonContactId }
+                : { targetUserId }),
+            text: options?.text ?? null,
+            requestMessage: options?.requestMessage ?? null,
+            sessionConfig: options?.sessionConfig ?? null,
+            sessionSelection: options?.sessionSelection,
+        });
+    }
+    async start() {
+        if (this.running)
+            return;
+        this.running = true;
+        // The single scoped RTDB client for this agent. Every RTDB consumer in
+        // the SDK (control poller, runtime-state publishers) threads this handle;
+        // the SDK never reads through core's deprecated module-global default,
+        // so multiple CanonAgents in one process cannot clobber each other.
+        this.rtdbHandle = initRTDBAuth(this.apiClient);
+        // 1. Authenticate
+        const { agentId } = await this.authManager.authenticate();
+        this.agentId = agentId;
+        console.log(`[canon-sdk] Authenticated as ${agentId}`);
+        // 2. Wire debouncer to handler
+        this.debouncer.setCallback(async (conversationId, messages, provenanceByMessageId) => {
+            this.rememberConversationId(conversationId);
+            await this.handleMessages(conversationId, messages, provenanceByMessageId);
+        });
+        // 3. Fetch conversations (used for delivery mode + session state)
+        let conversations = [];
+        try {
+            conversations = await this.apiClient.getConversations();
+            this.cachedConversationIds = conversations.map((c) => c.id);
+            this.rememberConversationMembers(conversations);
+        }
+        catch {
+            // Non-fatal — delivery mode will fall back to default
+        }
+        // 3a. Determine delivery mode
+        let mode = this.options.deliveryMode;
+        if (mode === 'auto') {
+            mode = 'sse';
+            console.log(`[canon-sdk] Auto-selected ${mode} mode (${conversations.length} conversations)`);
+        }
+        if (mode !== 'sse') {
+            throw new Error(`Unsupported deliveryMode: ${mode}. Use 'auto' or 'sse'.`);
+        }
+        // 3b. Fetch agent context (identity, owner, access level)
+        try {
+            this.agentContext = await this.apiClient.getAgentMe();
+            this.ensureApprovalManager(this.agentContext);
+        }
+        catch {
+            console.warn('[canon-sdk] Failed to fetch agent context — owner/access info unavailable');
+        }
+        // 3c. Initialize RTDB session state reporting (opt-in)
+        if (this.options.sessionState) {
+            const runtimeState = this.createRuntimeStatePublisher();
+            for (const id of this.cachedConversationIds) {
+                runtimeState?.writeSessionState(id, {
+                    cwd: process.cwd(),
+                    isActive: true,
+                    ...(this.options.clientType ? { clientType: this.options.clientType } : {}),
+                }).catch(() => { });
+            }
+            if (this.cachedConversationIds.length > 0) {
+                console.log(`[canon-sdk] Session state reported for ${this.cachedConversationIds.length} conversations`);
+            }
+        }
+        await this.baselineRuntimeControlSignals(this.cachedConversationIds);
+        this.startRuntimeControlPolling();
+        // 4. Start delivery
+        const { RealtimeManager } = await import('./realtime.js');
+        const rtm = new RealtimeManager(this.options.apiKey, this.debouncer, agentId, this.options.streamUrl, this.apiClient);
+        rtm.setOnAgentContext((ctx) => {
+            this.agentContext = ctx;
+            this.ensureApprovalManager(ctx);
+        });
+        rtm.setContactRequestHandlers({
+            onContactRequest: (request) => {
+                void this.handleContactRequestEvent(this.contactRequestHandler, request);
+            },
+            onContactApproved: (request) => {
+                void this.handleContactRequestEvent(this.contactApprovedHandler, request);
+            },
+        });
+        rtm.setContactGraphHandlers({
+            onContactAdded: (payload) => {
+                void this.handleContactGraphEvent(this.contactAddedHandler, payload);
+            },
+            onContactRemoved: (payload) => {
+                void this.handleContactGraphEvent(this.contactRemovedHandler, payload);
+            },
+        });
+        rtm.setConversationUpdatedHandler((payload) => {
+            this.handleConversationUpdated(payload);
+        });
+        rtm.setMessageUpdatedHandler((payload) => {
+            void this.handleMessageUpdatedEvent(payload);
+        });
+        rtm.setMessageDeletedHandler((payload) => {
+            this.sessionManager?.dropQueuedMessage(payload.conversationId, payload.messageId);
+        });
+        rtm.setConnectionHandlers({
+            onConnected: () => {
+                this.startRuntimeHeartbeat();
+                if (!this.sseConnectedLogged) {
+                    this.sseConnectedLogged = true;
+                    console.log('[canon-sdk] SSE stream connected');
+                }
+            },
+            onDisconnected: () => this.stopRuntimeHeartbeat(),
+        });
+        this.realtimeManager = rtm;
+        await rtm.start();
+    }
+    async createConversation(options) {
+        return this.apiClient.createConversation(options);
+    }
+    async updateTopic(conversationId, topic) {
+        return this.apiClient.updateTopic(conversationId, topic);
+    }
+    async leaveConversation(conversationId) {
+        return this.apiClient.leaveConversation(conversationId);
+    }
+    async updateConversationName(conversationId, name) {
+        return this.apiClient.updateConversationName(conversationId, name);
+    }
+    /**
+     * Add a member to a group conversation.
+     *
+     * Outcome depends on the target's `groupJoinPolicy` and the relationship
+     * graph:
+     * - `{ status: 'added' }` — the member was added immediately.
+     * - `{ status: 'pending', requestId }` — the target requires approval; the
+     *   server created a contact-request (kind: 'group_invite') routed to the
+     *   approver. The actual group join happens when that request is approved
+     *   (you can listen for `contact.approved` SSE events to know when).
+     *
+     * Throws `CanonApiError` for hard failures (block, inactive, owner-only,
+     * member cap, requester not authorized).
+     */
+    async addMember(conversationId, userId) {
+        return this.apiClient.addMember(conversationId, userId);
+    }
+    async removeMember(conversationId, userId) {
+        return this.apiClient.removeMember(conversationId, userId);
+    }
+    async uploadMedia(conversationId, data, mimeType, fileName) {
+        return this.apiClient.uploadMedia(conversationId, data, mimeType, fileName);
+    }
+    async handleContactRequestEvent(handler, request) {
+        if (!handler)
+            return;
+        try {
+            await handler(request);
+        }
+        catch (error) {
+            console.error('[canon-sdk] Contact-request handler failed:', error instanceof Error ? error.message : error);
+        }
+    }
+    async handleContactGraphEvent(handler, payload) {
+        if (!handler)
+            return;
+        try {
+            await handler(payload);
+        }
+        catch (error) {
+            console.error('[canon-sdk] Contact-graph handler failed:', error instanceof Error ? error.message : error);
+        }
+    }
+    async handleMessageUpdatedEvent(payload) {
+        if (!this.messageUpdatedHandler)
+            return;
+        try {
+            await this.messageUpdatedHandler(payload);
+        }
+        catch (error) {
+            console.error('[canon-sdk] Message-updated handler failed:', error instanceof Error ? error.message : error);
+        }
+    }
+    async stop() {
+        if (!this.running)
+            return;
+        this.running = false;
+        this.stopRuntimeControlPolling();
+        // Clear session state if enabled (uses cached IDs — no network call during shutdown)
+        const runtimeState = this.createRuntimeStatePublisher();
+        if (this.options.sessionState && runtimeState) {
+            for (const id of this.cachedConversationIds) {
+                Promise.resolve(runtimeState.clearSessionState(id)).catch(() => { });
+            }
+        }
+        if (runtimeState) {
+            for (const id of this.cachedConversationIds) {
+                Promise.resolve(runtimeState.clearTurnState(id)).catch(() => { });
+            }
+        }
+        await this.clearAgentRuntime();
+        this.realtimeManager?.stop();
+        this.sessionManager?.destroy();
+        this.authManager.destroy();
+        this.debouncer.destroy();
+        console.log('[canon-sdk] Stopped');
+    }
+    hasInterruptSupport() {
+        return Boolean(this.interruptHandler);
+    }
+    hasStopAndDropSupport() {
+        return Boolean(this.stopAndDropHandler);
+    }
+    hasNewSessionSupport() {
+        return Boolean(this.newSessionHandler);
+    }
+    hasRuntimeSignalSupport() {
+        return this.hasInterruptSupport() || this.hasStopAndDropSupport() || this.hasNewSessionSupport();
+    }
+    hasRuntimePrimitiveSupport() {
+        return this.primitiveHandlers.size > 0 || Boolean(this.primitiveFallbackHandler);
+    }
+    hasRuntimeControlSupport() {
+        return this.hasRuntimeSignalSupport() || this.hasRuntimePrimitiveSupport();
+    }
+    supportsInputInterrupt() {
+        return this.hasInterruptSupport() && this.options.runtimeDescriptor?.supportsInputInterrupt !== false;
+    }
+    buildRuntimeDescriptor() {
+        const source = this.options.runtimeDescriptor ?? DEFAULT_SDK_RUNTIME_DESCRIPTOR;
+        const hasInterrupt = this.hasInterruptSupport();
+        const hasStopAndDrop = this.hasStopAndDropSupport();
+        const hasNewSession = this.hasNewSessionSupport();
+        const commands = [...(source.commands ?? [])].filter((command) => {
+            if (command.dispatch.kind === 'signal') {
+                if (command.dispatch.signal === 'interrupt')
+                    return hasInterrupt;
+                if (command.dispatch.signal === 'stop_and_drop')
+                    return hasStopAndDrop;
+                if (command.dispatch.signal === 'new_session')
+                    return hasNewSession;
+                return false;
+            }
+            if (command.dispatch.kind !== 'primitive')
+                return true;
+            return this.primitiveHandlers.has(command.dispatch.primitive)
+                || Boolean(this.primitiveFallbackHandler);
+        });
+        const hasInterruptAction = commands.some((action) => action.dispatch.kind === 'signal' && action.dispatch.signal === 'interrupt');
+        const hasStopAndDropAction = commands.some((action) => action.dispatch.kind === 'signal' && action.dispatch.signal === 'stop_and_drop');
+        const hasNewSessionAction = commands.some((action) => action.dispatch.kind === 'signal' && action.dispatch.signal === 'new_session');
+        if (hasInterrupt && !hasInterruptAction) {
+            commands.push(RUNTIME_STOP_ACTION);
+        }
+        if (hasStopAndDrop && this.sessionManager && !hasStopAndDropAction) {
+            commands.push(RUNTIME_STOP_AND_DROP_ACTION);
+        }
+        if (hasNewSession && !hasNewSessionAction) {
+            commands.push(RUNTIME_NEW_SESSION_ACTION);
+        }
+        const hasCommandForPrimitive = (primitive) => commands.some((command) => (command.primitive === primitive
+            || (command.dispatch.kind === 'primitive' && command.dispatch.primitive === primitive)));
+        for (const primitive of this.primitiveHandlers.keys()) {
+            if (!hasCommandForPrimitive(primitive)) {
+                commands.push(STANDARD_PRIMITIVE_COMMANDS[primitive]);
+            }
+        }
+        return {
+            ...source,
+            supportsInterrupt: hasInterrupt,
+            supportsInputInterrupt: source.supportsInputInterrupt === false ? false : hasInterrupt,
+            commands: normalizeRuntimeCommandDescriptors(commands),
+        };
+    }
+    buildRuntimeCapabilities() {
+        return {
+            ...SDK_RUNTIME_CAPABILITIES,
+            supportsInterrupt: this.hasInterruptSupport(),
+            supportsInputInterrupt: this.supportsInputInterrupt(),
+            supportsQueue: Boolean(this.sessionManager),
+        };
+    }
+    async publishAgentRuntime() {
+        const publisher = this.createRuntimeStatePublisher();
+        if (!publisher)
+            return;
+        await publisher.publishAgentRuntime({
+            runtimeDescriptor: this.buildRuntimeDescriptor(),
+        });
+    }
+    startRuntimeHeartbeat() {
+        void this.publishAgentRuntime();
+        if (this.runtimeHeartbeatTimer)
+            return;
+        this.runtimeHeartbeatTimer = setInterval(() => {
+            void this.publishAgentRuntime();
+        }, AGENT_RUNTIME_HEARTBEAT_MS);
+        this.runtimeHeartbeatTimer.unref?.();
+    }
+    stopRuntimeHeartbeat() {
+        if (this.runtimeHeartbeatTimer) {
+            clearInterval(this.runtimeHeartbeatTimer);
+            this.runtimeHeartbeatTimer = null;
+        }
+        void this.clearAgentRuntime();
+    }
+    async clearAgentRuntime() {
+        await Promise.resolve(this.createRuntimeStatePublisher()?.clearAgentRuntime()).catch(() => { });
+    }
+    rememberConversationId(conversationId) {
+        if (this.cachedConversationIds.includes(conversationId))
+            return;
+        this.cachedConversationIds.push(conversationId);
+    }
+    rememberConversationMembers(conversations) {
+        for (const conversation of conversations) {
+            this.conversationMemberIds.set(conversation.id, [...(conversation.memberIds ?? [])]);
+        }
+    }
+    handleConversationUpdated(payload) {
+        const rawMemberIds = payload.changes.memberIds;
+        if (!Array.isArray(rawMemberIds))
+            return;
+        const memberIds = rawMemberIds.filter((id) => typeof id === 'string');
+        const hadPreviousMemberIds = this.conversationMemberIds.has(payload.conversationId);
+        const previousMemberIds = this.conversationMemberIds.get(payload.conversationId) ?? [];
+        const membershipChange = payload.membershipChange
+            ?? (hadPreviousMemberIds ? diffCanonMemberIds(previousMemberIds, memberIds) : null);
+        this.conversationMemberIds.set(payload.conversationId, memberIds);
+        if (membershipChange) {
+            this.pendingMembershipChanges.set(payload.conversationId, membershipChange);
+        }
+        if (this.agentId && !memberIds.includes(this.agentId)) {
+            this.cachedConversationIds = this.cachedConversationIds.filter((id) => id !== payload.conversationId);
+        }
+        else {
+            this.rememberConversationId(payload.conversationId);
+        }
+    }
+    buildGroupContext(input) {
+        return buildCanonGroupContext({
+            conversation: input.conversation,
+            messages: [...input.history, ...input.messages],
+            agentId: input.agent.agentId,
+            ownerId: input.agent.ownerId,
+            ownerName: input.agent.ownerName,
+            membershipChange: input.membershipChange,
+        });
+    }
+    /**
+     * Shared `/control` channel poller, configured to the agent-sdk host
+     * profile pinned by core's characterization tests: flat 2s single-flight
+     * cadence, parallel conversations, signal + primitive keys (no session),
+     * eager signal baseline, and TTL'd primitive dedupe released on successful
+     * consume. The poller talks only to the scoped RTDB handle captured in
+     * start() — never the module-global default client.
+     */
+    ensureControlPoller() {
+        if (this.controlPoller)
+            return this.controlPoller;
+        if (!this.rtdbHandle)
+            return null;
+        this.controlPoller = new ControlChannelPoller({
+            rtdb: this.rtdbHandle,
+            agentId: () => this.agentId,
+            conversationIds: () => this.cachedConversationIds,
+            cadence: { kind: 'fixed', intervalMs: RUNTIME_CONTROL_POLL_INTERVAL_MS },
+            pollOnStart: false,
+            conversationConcurrency: 'parallel',
+            handlers: {
+                signal: {
+                    handle: (event) => this.handleRuntimeSignalEvent(event),
+                    consumeOnError: true,
+                },
+                primitive: {
+                    handle: (event) => this.handleRuntimePrimitiveEvent(event),
+                    consumeOnError: true,
+                    ordering: 'sequential',
+                    dedupeTtlMs: RUNTIME_PRIMITIVE_DEDUPE_TTL_MS,
+                    dedupeMaxEntries: RUNTIME_PRIMITIVE_DEDUPE_MAX,
+                    releaseDedupeOnConsume: true,
+                },
+            },
+            onError: (error) => {
+                // Read/consume failures stay silent (the legacy loop swallowed them);
+                // handler-scope errors are host dispatch bugs worth surfacing.
+                if (error.scope === 'handler') {
+                    console.error(`[canon-sdk] Runtime control ${error.key ?? 'poll'} dispatch failed for ${error.conversationId}:`, error.error);
+                }
+            },
+        });
+        return this.controlPoller;
+    }
+    async baselineRuntimeControlSignals(conversationIds) {
+        if (!this.hasRuntimeSignalSupport())
+            return;
+        await this.ensureControlPoller()?.baseline(conversationIds);
+    }
+    startRuntimeControlPolling() {
+        if (!this.hasRuntimeControlSupport())
+            return;
+        this.ensureControlPoller()?.start();
+    }
+    stopRuntimeControlPolling() {
+        this.controlPoller?.stop();
+    }
+    async handleRuntimePrimitiveEvent(event) {
+        // Requests only belong to this runtime once primitive handlers exist —
+        // defer otherwise: the request stays in RTDB AND unseen, so a handler
+        // registered via onPrimitive() after start still receives it.
+        if (!this.hasRuntimePrimitiveSupport())
+            return { defer: true };
+        const { conversationId, requestId, value } = event;
+        const primitive = value.id;
+        // Unknown primitives and unhandled ids fall through so the poller
+        // consumes the request without dispatching, matching the legacy loop.
+        if (!isRuntimePrimitiveId(primitive))
+            return;
+        const handler = this.primitiveHandlers.get(primitive) ?? this.primitiveFallbackHandler;
+        if (!handler)
+            return;
+        await Promise.resolve(handler({
+            conversationId,
+            primitive,
+            args: normalizePrimitiveArgs(value.args),
+            requestId,
+            updatedAt: typeof value.updatedAt === 'number' ? value.updatedAt : undefined,
+            rawText: typeof value.rawText === 'string' ? value.rawText : undefined,
+            alias: typeof value.alias === 'string' ? value.alias : undefined,
+        })).catch((error) => {
+            console.error(`[canon-sdk] Runtime primitive ${primitive} handler failed for ${conversationId}:`, error);
+        });
+    }
+    async handleRuntimeSignalEvent(event) {
+        // Signals only belong to this runtime once signal handlers exist — defer
+        // otherwise: the signal stays in RTDB AND unseen, so a handler registered
+        // via on('interrupt' | ...) after start still receives it.
+        if (!this.hasRuntimeSignalSupport())
+            return { defer: true };
+        const { conversationId, type: signal, updatedAt } = event;
+        const handler = signal === 'new_session'
+            ? this.newSessionHandler
+            : signal === 'stop_and_drop'
+                ? this.stopAndDropHandler
+                : this.interruptHandler;
+        // No handler for this specific signal: fall through so the poller
+        // consumes the node without dispatching, matching the legacy loop.
+        if (!handler)
+            return;
+        const activeTurn = this.firstActiveTurn(conversationId);
+        const abortSignal = this.abortActiveTurns(conversationId);
+        const droppedMessages = signal === 'new_session'
+            ? this.sessionManager?.resetSession(conversationId) ?? []
+            : signal === 'stop_and_drop'
+                ? this.sessionManager?.dropQueued(conversationId) ?? []
+                : [];
+        const droppedMessageIds = droppedMessages.map((message) => message.id);
+        await Promise.all(droppedMessages.map((message) => {
+            if (message.metadata?.inboundDisposition !== 'queued')
+                return Promise.resolve();
+            return this.apiClient.updateMessageDisposition(conversationId, message.id, 'rejected').catch(() => { });
+        }));
+        await this.publishAcceptedRuntimeSignal(conversationId, signal, activeTurn, {
+            hasActiveTurn: Boolean(abortSignal),
+            droppedCount: droppedMessages.length,
+        });
+        await Promise.resolve(handler({
+            conversationId,
+            signal,
+            updatedAt: updatedAt || undefined,
+            abortSignal,
+            droppedMessageIds,
+        })).catch((error) => {
+            console.error(`[canon-sdk] Runtime ${signal} handler failed for ${conversationId}:`, error);
+        });
+    }
+    firstActiveTurn(conversationId) {
+        const turns = this.activeTurns.get(conversationId);
+        if (!turns || turns.size === 0)
+            return null;
+        return turns.values().next().value ?? null;
+    }
+    async publishAcceptedRuntimeSignal(conversationId, signal, activeTurn, outcome) {
+        if (!this.agentId)
+            return;
+        const shouldPublishInterrupted = signal === 'interrupt'
+            || signal === 'stop_and_drop'
+            || outcome.hasActiveTurn
+            || outcome.droppedCount > 0;
+        const runtimeState = shouldPublishInterrupted
+            ? this.createRuntimeStatePublisher()
+            : null;
+        if (runtimeState) {
+            await Promise.resolve(runtimeState.writeTurnState(conversationId, {
+                turnId: activeTurn?.turnId ?? null,
+                state: 'interrupted',
+                queueDepth: this.sessionManager?.getQueueDepth(conversationId) ?? 0,
+                currentSpeakerId: this.agentId,
+                activeMessageIds: activeTurn?.activeMessageIds ?? [],
+                capabilities: this.buildRuntimeCapabilities(),
+                ...(activeTurn?.openedAt ? { openedAt: activeTurn.openedAt } : {}),
+                completedAt: { '.sv': 'timestamp' },
+            })).catch(() => { });
+        }
+        await Promise.all([
+            this.apiClient.clearStreaming(conversationId).catch(() => { }),
+            this.typingSignals.clear(conversationId).catch(() => { }),
+        ]);
+    }
+    abortActiveTurns(conversationId) {
+        const controllers = this.activeAbortControllers.get(conversationId);
+        if (!controllers || controllers.size === 0)
+            return undefined;
+        const abortSignal = controllers.values().next().value?.signal;
+        for (const controller of controllers) {
+            controller.abort();
+        }
+        return abortSignal;
+    }
+    resolveBatchDeliveryIntent(messages) {
+        return messages.some((message) => normalizeTurnMetadata(message.metadata)?.deliveryIntent === 'interrupt')
+            ? 'interrupt'
+            : 'queue';
+    }
+    async markQueuedMessagesAccepted(conversationId, messages) {
+        await Promise.all(messages.map((message) => {
+            if (!message.id || normalizeTurnMetadata(message.metadata)?.inboundDisposition !== 'queued') {
+                return Promise.resolve();
+            }
+            return this.apiClient.updateMessageDisposition(conversationId, message.id, 'accepted_now').catch(() => { });
+        }));
+    }
+    async notifyMessageInterrupt(conversationId, abortSignal) {
+        if (!abortSignal || !this.interruptHandler)
+            return;
+        await Promise.resolve(this.interruptHandler({
+            conversationId,
+            signal: 'interrupt',
+            abortSignal,
+            droppedMessageIds: [],
+        })).catch((error) => {
+            console.error(`[canon-sdk] Runtime interrupt handler failed for ${conversationId}:`, error);
+        });
+    }
+    /**
+     * Builds a runtime-state publisher bound to this agent's scoped RTDB
+     * handle (captured in start()). Threading the handle keeps every
+     * publish on this agent's own credentials — without it the publisher
+     * would fall back to core's deprecated module-global RTDB client,
+     * where the last-started agent's token wins in multi-agent processes.
+     */
+    createRuntimeStatePublisher() {
+        if (!this.agentId)
+            return null;
+        return createRuntimeStatePublisher({
+            agentId: this.agentId,
+            clientType: this.options.clientType ?? 'generic',
+            hostMode: this.options.runtimeControlSurface === 'host',
+            ...(this.rtdbHandle ? { rtdb: this.rtdbHandle } : {}),
+        });
+    }
+    requireRuntimeStatePublisher() {
+        const publisher = this.createRuntimeStatePublisher();
+        if (!publisher) {
+            throw new Error('Canon agent must be started before publishing runtime operations.');
+        }
+        return publisher;
+    }
+    async handleMessages(conversationId, messages, provenanceByMessageId) {
+        const actionableMessages = this.filterApprovalReplyMessages(conversationId, messages);
+        if (actionableMessages.length === 0) {
+            return;
+        }
+        messages = actionableMessages;
+        if (!this.handler) {
+            console.warn(`[canon-sdk] No message handler registered — messages for ${conversationId} dropped. Call agent.on('message', handler) before starting.`);
+            return;
+        }
+        const deliveryIntent = this.resolveBatchDeliveryIntent(messages);
+        const shouldInterrupt = deliveryIntent === 'interrupt' && this.hasInterruptSupport();
+        const abortSignal = shouldInterrupt ? this.abortActiveTurns(conversationId) : undefined;
+        await this.notifyMessageInterrupt(conversationId, abortSignal);
+        if (this.sessionManager) {
+            await this.sessionManager.enqueue(conversationId, messages, async (session, newMessages) => {
+                await this.executeHandler(conversationId, newMessages, session, provenanceByMessageId);
+            }, { toFront: shouldInterrupt });
+        }
+        else {
+            await this.executeHandler(conversationId, messages, undefined, provenanceByMessageId);
+        }
+    }
+    async executeHandler(conversationId, messages, session, provenanceByMessageId) {
+        if (!this.handler)
+            return;
+        await this.markQueuedMessagesAccepted(conversationId, messages);
+        const turnId = randomUUID();
+        const turnOpenedAt = Date.now();
+        let turnState = 'thinking';
+        let shouldPersistTurnState = false;
+        let durableMessageSequence = 0;
+        const agentId = this.agentId;
+        const runtimeState = this.createRuntimeStatePublisher();
+        const queueDepth = () => this.sessionManager?.getQueueDepth(conversationId) ?? 0;
+        const abortController = new AbortController();
+        const throwIfAborted = () => {
+            if (abortController.signal.aborted) {
+                throw createTurnAbortError();
+            }
+        };
+        const activeControllers = this.activeAbortControllers.get(conversationId) ?? new Set();
+        activeControllers.add(abortController);
+        this.activeAbortControllers.set(conversationId, activeControllers);
+        const activeTurns = this.activeTurns.get(conversationId) ?? new Map();
+        activeTurns.set(abortController, {
+            turnId,
+            openedAt: turnOpenedAt,
+            activeMessageIds: messages.map((message) => message.id).filter(Boolean),
+        });
+        this.activeTurns.set(conversationId, activeTurns);
+        const writeTurn = async (state) => {
+            if (!runtimeState || !agentId)
+                return;
+            turnState = state;
+            const isOpenTurn = state === 'thinking'
+                || state === 'streaming'
+                || state === 'tool'
+                || state === 'waiting_input';
+            await Promise.resolve(runtimeState.writeTurnState(conversationId, {
+                turnId,
+                state,
+                queueDepth: queueDepth(),
+                currentSpeakerId: agentId,
+                capabilities: this.buildRuntimeCapabilities(),
+                openedAt: turnOpenedAt,
+                ...(isOpenTurn ? { turnUpdatedAt: Date.now() } : {}),
+                ...(state === 'completed' || state === 'interrupted' || state === 'idle'
+                    ? { completedAt: { '.sv': 'timestamp' } }
+                    : {}),
+            })).catch(() => { });
+        };
+        const turnOutput = createTurnOutputController({
+            turnId,
+            mode: 'snapshot',
+            writeSnapshot: (snapshot) => this.apiClient.setStreaming({
+                conversationId,
+                text: snapshot.text,
+                status: snapshot.status,
+                messageId: snapshot.messageId,
+                turnId: snapshot.turnId,
+                blocks: snapshot.blocks,
+            }),
+            clearSnapshot: () => this.apiClient.clearStreaming(conversationId),
+        });
+        const setLiveState = async (state, text, streamingStatus) => {
+            throwIfAborted();
+            await writeTurn(state);
+            if (streamingStatus) {
+                await turnOutput.setStatus(streamingStatus, text ?? '');
+            }
+        };
+        // Show thinking indicator and keep it alive (5s client-side expiry)
+        try {
+            await this.typingSignals.start(conversationId, 'thinking');
+        }
+        catch {
+            // Non-critical
+        }
+        await setLiveState('thinking', 'Thinking...', 'thinking');
+        const thinkingKeepalive = setInterval(() => {
+            if (turnState === 'thinking') {
+                turnOutput.setStatus('thinking', 'Thinking...').catch(() => { });
+            }
+        }, 3500);
+        try {
+            // Fetch hydrated history/context from API
+            const page = await this.apiClient.getMessagesPage(conversationId, this.options.historyLimit);
+            const history = page.messages;
+            const historyById = new Map(history.map((message) => [message.id, message]));
+            const hydratedMessages = messages.map((message) => {
+                const hydrated = historyById.get(message.id);
+                if (hydrated)
+                    return hydrated;
+                return {
+                    ...message,
+                    attachments: message.attachments ?? [],
+                };
+            });
+            // If sessions enabled, seed the session with fetched history
+            if (this.sessionManager && session) {
+                this.sessionManager.seedHistory(conversationId, history);
+            }
+            // Get conversation info
+            const conversations = await this.apiClient.getConversations();
+            this.rememberConversationMembers(conversations);
+            const conversation = conversations.find((c) => c.id === conversationId);
+            if (!conversation)
+                return;
+            // Build reply functions
+            const replyFinal = async (text, options) => {
+                throwIfAborted();
+                try {
+                    await this.typingSignals.start(conversationId, 'typing');
+                }
+                catch { }
+                throwIfAborted();
+                const sendOptions = withActiveSelfContext(options);
+                const turnTrail = turnOutput.getFinalTrail();
+                const result = await sendDurableMessage(text, {
+                    ...sendOptions,
+                    metadata: {
+                        ...(sendOptions.metadata ?? {}),
+                        turnId,
+                        turnSemantics: 'turn_complete',
+                        ...(turnTrail.length > 0 ? { turnTrail } : {}),
+                    },
+                }, ['sdk', 'final', conversationId, turnId]);
+                await sleep(FINAL_MESSAGE_HANDOFF_MS);
+                try {
+                    await this.typingSignals.clear(conversationId);
+                }
+                catch { }
+                return result;
+            };
+            const replyProgress = async (text, options) => {
+                throwIfAborted();
+                await setLiveState('streaming', text, 'streaming');
+                if (!options?.durable) {
+                    return { turnId, durable: false, messageId: null };
+                }
+                throwIfAborted();
+                const { durable: _durable, ...sendOptions } = options;
+                const sendOptionsWithContext = withActiveSelfContext(sendOptions);
+                const result = await this.apiClient.sendMessage(conversationId, text, {
+                    ...sendOptionsWithContext,
+                    metadata: {
+                        ...(sendOptionsWithContext.metadata ?? {}),
+                        turnId,
+                        turnSemantics: 'progress',
+                    },
+                });
+                return { turnId, durable: true, messageId: result.messageId };
+            };
+            // Enrich history messages with isOwner
+            if (this.agentContext?.ownerId) {
+                const ownerId = this.agentContext.ownerId;
+                for (const m of history) {
+                    m.isOwner = m.senderId === ownerId;
+                }
+            }
+            const latestMessage = hydratedMessages[hydratedMessages.length - 1] ?? null;
+            let replyContext = latestMessage
+                ? resolveCanonReplyContext({ message: latestMessage, messages: history })
+                : null;
+            const resolvedActiveSelfContextId = resolveMessageActiveSelfContextId({
+                messageId: latestMessage?.id,
+                activeSelfContextIdByMessageId: page.activeSelfContextIdByMessageId,
+            });
+            const selfContexts = selectActiveSelfContexts(page.selfContexts, resolvedActiveSelfContextId);
+            const activeSelfContextId = selfContexts.length > 0 ? resolvedActiveSelfContextId : null;
+            const withActiveSelfContext = (options) => {
+                const base = { ...(options ?? {}) };
+                if (base.selfContextId !== undefined)
+                    return base;
+                return activeSelfContextId ? { ...base, selfContextId: activeSelfContextId } : base;
+            };
+            const sendDurableMessage = (text, options, fallbackMessageIdParts) => {
+                const messageId = options?.messageId
+                    ?? buildSdkMessageId([...fallbackMessageIdParts, durableMessageSequence += 1]);
+                return sendMessageWithRetry(this.apiClient, conversationId, text, {
+                    ...(options ?? {}),
+                    messageId,
+                }, {
+                    sleep: (ms) => sleepWithAbort(ms, abortController.signal),
+                });
+            };
+            // Build agent context (fallback to minimal if not yet received)
+            const agent = this.agentContext ?? {
+                agentId: this.agentId,
+                ownerId: '',
+                ownerName: '',
+                discoverable: false,
+                inboundPolicy: 'approval-required',
+                groupJoinPolicy: 'approval-required',
+            };
+            const provenance = latestMessage
+                ? resolveRuntimeProvenance({
+                    provenance: provenanceByMessageId?.get(latestMessage.id) ?? null,
+                    conversationId,
+                    conversationType: conversation.type,
+                    memberCount: conversation.memberIds.length,
+                    senderId: latestMessage.senderId,
+                    senderName: latestMessage.senderName ?? latestMessage.senderId,
+                    senderType: latestMessage.senderType,
+                    isOwner: latestMessage.isOwner,
+                    agentId: agent.agentId,
+                    mentions: latestMessage.mentions,
+                    activeSelfContextId,
+                    selfContexts,
+                })
+                : resolveRuntimeProvenance({
+                    conversationId,
+                    conversationType: conversation.type,
+                    memberCount: conversation.memberIds.length,
+                    senderId: '',
+                    senderType: 'human',
+                    isOwner: false,
+                    agentId: agent.agentId,
+                    activeSelfContextId,
+                    selfContexts,
+                });
+            if (replyContext?.found && replyContext.attachments?.length) {
+                try {
+                    const materializedReply = await materializeReplyContextMedia(replyContext, {
+                        agentId: agent.agentId,
+                        conversationId,
+                    });
+                    replyContext = materializedReply.replyContext;
+                }
+                catch (error) {
+                    console.error(`[canon-sdk] Failed to materialize reply context media for ${conversationId}:`, error instanceof Error ? error.message : error);
+                }
+            }
+            const membershipChange = this.pendingMembershipChanges.get(conversationId) ?? null;
+            this.pendingMembershipChanges.delete(conversationId);
+            const groupContext = this.buildGroupContext({
+                conversation,
+                history,
+                messages: hydratedMessages,
+                agent,
+                membershipChange,
+            });
+            const participationHistory = buildParticipationHistorySnapshot(history, agent.agentId);
+            const turnContext = buildCanonTurnContextV2({
+                content: latestMessage ? renderCanonHostInboundContent(latestMessage) : '[Empty message]',
+                conversationId,
+                participantContext: {
+                    conversationType: conversation.type,
+                    memberCount: conversation.memberIds.length,
+                    senderType: latestMessage?.senderType ?? provenance.sender.type,
+                    senderName: latestMessage?.senderName
+                        ?? provenance.sender.name
+                        ?? latestMessage?.senderId
+                        ?? provenance.sender.id
+                        ?? 'unknown',
+                    isOwner: provenance.sender.isOwner,
+                    mentionedAgent: provenance.mentionedAgent,
+                    ...(groupContext ? { groupContext } : {}),
+                    ...(groupContext && membershipChange ? { groupContextMode: 'membership_change' } : {}),
+                    recentSenderTypes: participationHistory.recentSenderTypes,
+                    recentHumanCount: participationHistory.recentHumanCount,
+                    recentAgentCount: participationHistory.recentAgentCount,
+                    consecutiveAgentTurns: participationHistory.consecutiveAgentTurns,
+                    currentAgentStreakStartedByHuman: participationHistory.currentAgentStreakStartedByHuman,
+                },
+                behavior: page.behavior ?? conversation.behavior,
+                selfContexts,
+                activeSelfContextId,
+                provenance,
+                replyContext,
+                message: latestMessage ?? undefined,
+            });
+            const requestedTurnMode = latestMessage
+                ? normalizeTurnMetadata(latestMessage.metadata)?.requestedTurnMode ?? null
+                : null;
+            // Build context methods bound to this conversation
+            const deleteMessage = (messageId) => this.apiClient.deleteMessage(conversationId, messageId);
+            const markAsRead = () => this.apiClient.markAsRead(conversationId);
+            const leave = () => this.apiClient.leaveConversation(conversationId);
+            const react = (messageId, emoji) => this.apiClient.react(conversationId, messageId, emoji);
+            const addMember = (userId) => this.apiClient.addMember(conversationId, userId);
+            const removeMember = (userId) => this.apiClient.removeMember(conversationId, userId);
+            const sendContextualMessage = (target, text, options) => this.apiClient.sendContextualMessage({
+                sourceConversationId: conversationId,
+                ...target,
+                text,
+                ...options,
+                messageOptions: {
+                    ...(options.messageOptions ?? {}),
+                    metadata: {
+                        ...(options.messageOptions?.metadata ?? {}),
+                        turnId,
+                        turnSemantics: 'turn_complete',
+                    },
+                },
+            });
+            const reachOut = (card, options) => this.reachOut(card, {
+                ...(options ?? {}),
+                sourceConversationId: conversationId,
+            });
+            const requestApproval = async (request) => {
+                throwIfAborted();
+                const manager = this.ensureApprovalManager(agent);
+                if (!manager) {
+                    return { decision: 'deny' };
+                }
+                shouldPersistTurnState = true;
+                try {
+                    try {
+                        await turnOutput.addBlock({
+                            id: `approval:${request.runtimeId ?? request.toolName}:${turnId}`,
+                            kind: 'approval',
+                            status: 'pending',
+                            title: request.toolSummary ?? request.toolName,
+                            summary: request.risk ?? request.category,
+                        });
+                        await turnOutput.waitingInput();
+                    }
+                    catch { }
+                    await writeTurn('waiting_input');
+                    try {
+                        await this.typingSignals.clear(conversationId);
+                    }
+                    catch { }
+                    const result = await manager.requestApproval(conversationId, request.toolName, request.toolInput ?? {}, {
+                        riskLevel: request.riskLevel,
+                        risk: request.risk,
+                        category: request.category,
+                        runtimeId: request.runtimeId,
+                        turnId: request.turnId ?? turnId,
+                        native: request.native,
+                        toolSummary: request.toolSummary,
+                        details: request.details,
+                        ignoreSessionRules: request.ignoreSessionRules,
+                        allowSessionRule: request.allowSessionRule,
+                    });
+                    throwIfAborted();
+                    shouldPersistTurnState = false;
+                    try {
+                        await turnOutput.completeBlock(`approval:${request.runtimeId ?? request.toolName}:${turnId}`, {
+                            summary: `Decision: ${result.decision}`,
+                        });
+                    }
+                    catch { }
+                    try {
+                        await this.typingSignals.start(conversationId, 'thinking');
+                    }
+                    catch { }
+                    await setLiveState('thinking', 'Thinking...', 'thinking');
+                    return result;
+                }
+                catch (error) {
+                    if (abortController.signal.aborted || isAbortLikeError(error)) {
+                        throw error;
+                    }
+                    shouldPersistTurnState = false;
+                    return { decision: 'deny' };
+                }
+            };
+            const requestRuntimeInput = async (request) => {
+                throwIfAborted();
+                const inputId = safeRuntimeInputId(request.inputId, request.kind);
+                const timeoutMs = Math.max(1_000, request.timeoutMs ?? DEFAULT_RUNTIME_INPUT_TIMEOUT_MS);
+                const expiresAtMs = Date.now() + timeoutMs;
+                const expiresAt = new Date(expiresAtMs).toISOString();
+                let result = { status: 'timeout', inputId };
+                let requestCreated = false;
+                shouldPersistTurnState = true;
+                try {
+                    await this.apiClient.createRuntimeInputRequest({
+                        conversationId,
+                        inputId,
+                        kind: request.kind,
+                        expiresAt: expiresAtMs,
+                        responseUserId: agent.ownerId,
+                        title: request.title,
+                        prompt: request.prompt,
+                        ...(request.choices ? { choices: request.choices } : {}),
+                        ...(request.questions ? { questions: request.questions } : {}),
+                        ...(request.secretName ? { secretName: request.secretName } : {}),
+                        ...(request.native ? { native: request.native } : {}),
+                        ...(request.sensitive !== undefined ? { sensitive: request.sensitive } : {}),
+                        turnId: request.turnId ?? turnId,
+                    });
+                    requestCreated = true;
+                    try {
+                        await turnOutput.addBlock({
+                            id: `input:${inputId}`,
+                            kind: 'input',
+                            status: 'pending',
+                            title: request.title ?? request.prompt ?? request.kind,
+                            summary: request.kind,
+                        });
+                        await turnOutput.waitingInput();
+                    }
+                    catch { }
+                    await writeTurn('waiting_input');
+                    try {
+                        await this.typingSignals.clear(conversationId);
+                    }
+                    catch { }
+                    // The shared engine owns the poll-with-abort loop + post-deadline
+                    // consume; the request was already created above, so the descriptor's
+                    // create is a no-op. On abort the manager fires the descriptor's
+                    // built-in cancel (consume({ cancel: true })) via the passed signal.
+                    result = await this.ensureRuntimeRequestManager().request('input', conversationId, { kind: request.kind }, {
+                        requestId: inputId,
+                        expiresAt: expiresAtMs,
+                        signal: abortController.signal,
+                    });
+                    const outcome = buildRuntimeInputOutcome(inputId, result.status, {
+                        kind: request.kind,
+                        reason: result.status,
+                    });
+                    await sendDurableMessage(outcome.text, {
+                        metadata: {
+                            ...outcome.metadata,
+                            turnId: request.turnId ?? turnId,
+                            turnSemantics: 'control',
+                            replyBehavior: 'suppress_auto_reply',
+                        },
+                    }, ['sdk', 'runtime-input-outcome', conversationId, request.turnId ?? turnId, inputId, result.status]);
+                    throwIfAborted();
+                    shouldPersistTurnState = false;
+                    try {
+                        await turnOutput.completeBlock(`input:${inputId}`, {
+                            summary: `Input ${result.status}`,
+                        });
+                    }
+                    catch { }
+                    try {
+                        await this.typingSignals.start(conversationId, 'thinking');
+                    }
+                    catch { }
+                    await setLiveState('thinking', 'Thinking...', 'thinking');
+                    return result;
+                }
+                catch (error) {
+                    if (abortController.signal.aborted || isAbortLikeError(error)) {
+                        if (requestCreated) {
+                            // Abort landing before the manager wired its cancel (e.g. during
+                            // the pre-request writeTurn/typing round-trips) leaves the
+                            // server-side request pending + responder-actionable; cancel it so
+                            // a late (possibly sensitive) answer can't resolve a dead request.
+                            await this.apiClient
+                                .consumeRuntimeInputResponse({ conversationId, inputId, cancel: true })
+                                .catch(() => { });
+                        }
+                        throw error;
+                    }
+                    if (!requestCreated) {
+                        shouldPersistTurnState = false;
+                        throw error;
+                    }
+                    shouldPersistTurnState = false;
+                    return result;
+                }
+            };
+            const sendCard = async (request) => {
+                throwIfAborted();
+                const cardId = safeRuntimeCardId(request.cardId ?? request.card.cardId);
+                const explicitExpiresAt = request.expiresAt instanceof Date
+                    ? request.expiresAt.getTime()
+                    : typeof request.expiresAt === 'number'
+                        ? request.expiresAt
+                        : typeof request.expiresAt === 'string'
+                            ? Date.parse(request.expiresAt)
+                            : null;
+                const timeoutMs = Math.max(1_000, request.timeoutMs ?? DEFAULT_RUNTIME_INPUT_TIMEOUT_MS);
+                const expiresAtMs = explicitExpiresAt && Number.isFinite(explicitExpiresAt)
+                    ? explicitExpiresAt
+                    : Date.now() + timeoutMs;
+                // Fire-and-forget: post the durable card and return. The backend treats an
+                // action-less card as display (no pending state, no response expected).
+                await this.apiClient.createRuntimeCardRequest(buildRuntimeCardCreateArgs({ request, conversationId, cardId, fallbackTurnId: turnId, expiresAtMs }));
+                try {
+                    await turnOutput.addBlock({
+                        id: `card:${cardId}`,
+                        kind: 'status',
+                        status: 'completed',
+                        title: request.card.title,
+                        summary: request.card.template ?? 'runtime card',
+                    });
+                }
+                catch { }
+                return { status: 'displayed', cardId };
+            };
+            const requestCard = async (request) => {
+                throwIfAborted();
+                // Action-less cards are fire-and-forget display/report cards — never block.
+                const hasActions = Array.isArray(request.card.blocks)
+                    && request.card.blocks.some((block) => block.kind === 'actions');
+                if (!hasActions)
+                    return sendCard(request);
+                const cardId = safeRuntimeCardId(request.cardId ?? request.card.cardId);
+                const explicitExpiresAt = request.expiresAt instanceof Date
+                    ? request.expiresAt.getTime()
+                    : typeof request.expiresAt === 'number'
+                        ? request.expiresAt
+                        : typeof request.expiresAt === 'string'
+                            ? Date.parse(request.expiresAt)
+                            : null;
+                const timeoutMs = Math.max(1_000, request.timeoutMs ?? DEFAULT_RUNTIME_INPUT_TIMEOUT_MS);
+                const expiresAtMs = explicitExpiresAt && Number.isFinite(explicitExpiresAt)
+                    ? explicitExpiresAt
+                    : Date.now() + timeoutMs;
+                let result = { status: 'timeout', cardId };
+                let requestCreated = false;
+                let requestResolved = false;
+                shouldPersistTurnState = true;
+                try {
+                    await this.apiClient.createRuntimeCardRequest(buildRuntimeCardCreateArgs({ request, conversationId, cardId, fallbackTurnId: turnId, expiresAtMs }));
+                    requestCreated = true;
+                    try {
+                        await turnOutput.addBlock({
+                            id: `card:${cardId}`,
+                            kind: 'input',
+                            status: 'pending',
+                            title: request.card.title,
+                            summary: request.card.template ?? 'runtime card',
+                        });
+                        await turnOutput.waitingInput();
+                    }
+                    catch { }
+                    await writeTurn('waiting_input');
+                    try {
+                        await this.typingSignals.clear(conversationId);
+                    }
+                    catch { }
+                    // The shared engine owns the poll-with-abort loop + post-deadline
+                    // consume; the request was already created above, so the descriptor's
+                    // create is a no-op. On abort the manager fires the descriptor's
+                    // built-in cancel (consume({ cancel: true })) via the passed signal.
+                    result = await this.ensureRuntimeRequestManager().request('card', conversationId, { card: request.card }, {
+                        requestId: cardId,
+                        expiresAt: expiresAtMs,
+                        signal: abortController.signal,
+                    });
+                    requestResolved = true;
+                    // The interactive path never yields 'displayed' (that returns early via
+                    // sendCard); narrow for buildRuntimeCardOutcome's resolution status.
+                    const resolutionStatus = result.status === 'displayed' ? 'timeout' : result.status;
+                    const outcome = buildRuntimeCardOutcome(cardId, resolutionStatus, {
+                        reason: resolutionStatus,
+                    });
+                    await sendDurableMessage(outcome.text, {
+                        metadata: {
+                            ...outcome.metadata,
+                            turnId: request.turnId ?? turnId,
+                            turnSemantics: 'control',
+                            replyBehavior: 'suppress_auto_reply',
+                        },
+                    }, ['sdk', 'runtime-card-outcome', conversationId, request.turnId ?? turnId, cardId, resolutionStatus]);
+                    throwIfAborted();
+                    shouldPersistTurnState = false;
+                    try {
+                        await turnOutput.completeBlock(`card:${cardId}`, {
+                            summary: `Card ${result.status}`,
+                        });
+                    }
+                    catch { }
+                    try {
+                        await this.typingSignals.start(conversationId, 'thinking');
+                    }
+                    catch { }
+                    await setLiveState('thinking', 'Thinking...', 'thinking');
+                    return result;
+                }
+                catch (error) {
+                    const shouldSendInterruptedOutcome = requestCreated && !requestResolved;
+                    if (abortController.signal.aborted || isAbortLikeError(error)) {
+                        if (shouldSendInterruptedOutcome) {
+                            // Cancel the server-side card if the abort landed before the
+                            // manager wired its cancel, so a late action can't resolve a dead
+                            // request (mirrors the runtime-input path).
+                            await this.apiClient
+                                .consumeRuntimeCardResponse({ conversationId, cardId, cancel: true })
+                                .catch(() => { });
+                            const outcome = buildRuntimeCardOutcome(cardId, 'cancelled', { reason: 'interrupted' });
+                            await sendDurableMessage(outcome.text, {
+                                metadata: {
+                                    ...outcome.metadata,
+                                    turnId: request.turnId ?? turnId,
+                                    turnSemantics: 'control',
+                                    replyBehavior: 'suppress_auto_reply',
+                                },
+                            }, ['sdk', 'runtime-card-outcome', conversationId, request.turnId ?? turnId, cardId, 'interrupted']).catch(() => { });
+                        }
+                        throw error;
+                    }
+                    if (!requestCreated) {
+                        shouldPersistTurnState = false;
+                        throw error;
+                    }
+                    shouldPersistTurnState = false;
+                    return result;
+                }
+            };
+            const uploadFile = (filePath, options) => uploadMediaFile(this.apiClient, conversationId, filePath, options);
+            const replyWithFile = async (filePath, text = '', options) => {
+                throwIfAborted();
+                try {
+                    await this.typingSignals.start(conversationId, 'typing');
+                }
+                catch { }
+                throwIfAborted();
+                try {
+                    const turnTrail = turnOutput.getFinalTrail();
+                    const result = await sendMediaFileMessage(this.apiClient, conversationId, filePath, text, {
+                        ...(options?.replyTo ? { replyTo: options.replyTo } : {}),
+                        ...(options?.replyToPosition != null
+                            ? { replyToPosition: options.replyToPosition }
+                            : {}),
+                        ...(options?.mentions ? { mentions: options.mentions } : {}),
+                        ...withActiveSelfContext(options?.selfContextId !== undefined
+                            ? { selfContextId: options.selfContextId }
+                            : undefined),
+                        metadata: {
+                            ...(options?.metadata ?? {}),
+                            turnId,
+                            turnSemantics: 'turn_complete',
+                            ...(turnTrail.length > 0 ? { turnTrail } : {}),
+                        },
+                        ...(options?.fileName ? { fileName: options.fileName } : {}),
+                        ...(options?.mimeType ? { mimeType: options.mimeType } : {}),
+                        ...(options?.durationMs != null ? { durationMs: options.durationMs } : {}),
+                    });
+                    await sleep(FINAL_MESSAGE_HANDOFF_MS);
+                    return result;
+                }
+                finally {
+                    try {
+                        await this.typingSignals.clear(conversationId);
+                    }
+                    catch { }
+                }
+            };
+            // Invoke handler
+            throwIfAborted();
+            await this.handler({
+                messages: hydratedMessages,
+                history,
+                replyContext,
+                conversationId,
+                conversation,
+                ...(groupContext ? { groupContext } : {}),
+                replyFinal,
+                replyProgress,
+                deleteMessage,
+                markAsRead,
+                leave,
+                react,
+                addMember,
+                removeMember,
+                sendContextualMessage,
+                reachOut,
+                agent,
+                activeSelfContextId,
+                selfContexts,
+                provenance,
+                turnContext,
+                requestedTurnMode,
+                requestApproval,
+                requestRuntimeInput,
+                requestCard,
+                sendCard,
+                abortSignal: abortController.signal,
+                media: {
+                    materialize: (message = hydratedMessages[hydratedMessages.length - 1], options) => {
+                        if (!message)
+                            return Promise.resolve([]);
+                        return materializeMessageMedia(message, {
+                            agentId: agent.agentId,
+                            conversationId,
+                            ...(options ?? {}),
+                        });
+                    },
+                    uploadFile,
+                    replyWithFile,
+                },
+                session: session
+                    ? {
+                        id: session.id,
+                        messages: session.messages,
+                        metadata: session.metadata,
+                        queueDepth: queueDepth(),
+                    }
+                    : undefined,
+                turn: {
+                    id: turnId,
+                    get state() {
+                        return turnState;
+                    },
+                    setThinking: async (text) => {
+                        await setLiveState('thinking', text ?? 'Thinking...', 'thinking');
+                    },
+                    setStreaming: async (text) => {
+                        await setLiveState('streaming', text, 'streaming');
+                    },
+                    appendDelta: (delta) => {
+                        throwIfAborted();
+                        turnState = 'streaming';
+                        turnOutput.appendDelta(delta);
+                        void writeTurn('streaming');
+                    },
+                    appendBlock: (block) => {
+                        throwIfAborted();
+                        turnState = 'streaming';
+                        turnOutput.appendBlock(block);
+                        void writeTurn('streaming');
+                    },
+                    appendTextSegmentDelta: (id, delta) => {
+                        throwIfAborted();
+                        turnState = 'streaming';
+                        turnOutput.appendTextSegmentDelta(id, delta);
+                        void writeTurn('streaming');
+                    },
+                    replaceTextSegmentSnapshot: (id, text) => {
+                        throwIfAborted();
+                        turnState = 'streaming';
+                        turnOutput.replaceTextSegmentSnapshot(id, text);
+                        void writeTurn('streaming');
+                    },
+                    addBlock: async (block) => {
+                        throwIfAborted();
+                        return turnOutput.addBlock(block);
+                    },
+                    updateBlock: async (id, patch) => {
+                        throwIfAborted();
+                        return turnOutput.updateBlock(id, patch);
+                    },
+                    completeBlock: async (id, patch) => {
+                        throwIfAborted();
+                        return turnOutput.completeBlock(id, patch);
+                    },
+                    failBlock: async (id, patch) => {
+                        throwIfAborted();
+                        return turnOutput.failBlock(id, patch);
+                    },
+                    replaceSnapshot: async (text) => {
+                        await setLiveState('streaming', text, 'streaming');
+                    },
+                    flush: async () => {
+                        await turnOutput.flush();
+                    },
+                    clear: async () => {
+                        await turnOutput.clear();
+                    },
+                    setTool: async (text) => {
+                        await writeTurn('tool');
+                        await turnOutput.addBlock({
+                            id: `tool:${Date.now()}`,
+                            kind: 'tool',
+                            status: 'running',
+                            title: text,
+                        });
+                        await turnOutput.setStatus('tool');
+                    },
+                    setWaitingInput: async (text) => {
+                        shouldPersistTurnState = true;
+                        try {
+                            await turnOutput.waitingInput();
+                        }
+                        catch { }
+                        await writeTurn('waiting_input');
+                        try {
+                            await this.typingSignals.clear(conversationId);
+                        }
+                        catch { }
+                        if (text) {
+                            await sendDurableMessage(text, {
+                                metadata: {
+                                    turnId,
+                                    turnSemantics: 'control',
+                                    replyBehavior: 'suppress_auto_reply',
+                                },
+                            }, ['sdk', 'waiting-input-note', conversationId, turnId]);
+                        }
+                    },
+                },
+            });
+            // Auto-mark conversation as read after successful processing
+            if (this.options.autoMarkRead) {
+                try {
+                    await this.apiClient.markAsRead(conversationId);
+                }
+                catch {
+                    // Non-critical
+                }
+            }
+        }
+        catch (err) {
+            if (abortController.signal.aborted || isAbortLikeError(err)) {
+                await writeTurn('interrupted');
+                return;
+            }
+            console.error(`[canon-sdk] Handler error for ${conversationId}:`, err);
+            await writeTurn('interrupted');
+        }
+        finally {
+            const activeControllers = this.activeAbortControllers.get(conversationId);
+            activeControllers?.delete(abortController);
+            if (activeControllers?.size === 0) {
+                this.activeAbortControllers.delete(conversationId);
+            }
+            const activeTurns = this.activeTurns.get(conversationId);
+            activeTurns?.delete(abortController);
+            if (activeTurns?.size === 0) {
+                this.activeTurns.delete(conversationId);
+            }
+            clearInterval(thinkingKeepalive);
+            // Always clear typing when done
+            try {
+                await this.typingSignals.clear(conversationId);
+            }
+            catch { }
+            try {
+                await turnOutput.clear();
+            }
+            catch { }
+            if (runtimeState && !shouldPersistTurnState) {
+                await Promise.resolve(runtimeState.clearTurnState(conversationId)).catch(() => { });
+            }
+        }
+    }
+    // Static registration helpers (unauthenticated)
+    static async register(options) {
+        const { baseUrl, ...body } = options;
+        return CanonClient.register(baseUrl, body);
+    }
+    static async checkStatus(requestId, options) {
+        const baseUrl = typeof options === 'string' ? options : options?.baseUrl;
+        const pollToken = typeof options === 'string' ? undefined : options?.pollToken;
+        return CanonClient.checkStatus(baseUrl, requestId, pollToken);
+    }
+    static async ackStatus(requestId, options) {
+        const baseUrl = typeof options === 'string' ? options : options?.baseUrl;
+        const pollToken = typeof options === 'string' ? undefined : options?.pollToken;
+        await CanonClient.ackRegistrationStatus(baseUrl, requestId, pollToken);
+    }
+}