@canonmsg/agent-sdk 11.2.1 → 12.1.0

package/dist/canon-agent.js

@@ -1,2531 +0,0 @@
-import { readArtifactContext } from '@canonmsg/core';
-import { ApprovalManager, RuntimeRequestManager, runtimeInputDescriptor, runtimeCardDescriptor, CanonClient, ControlChannelPoller, buildCanonTurnContextV2, buildCanonGroupContext, buildParticipationHistorySnapshot, createTurnOutputController, createRuntimeStatePublisher, createRuntimeHeartbeat, createTypingStatusPublisher, diffCanonMemberIds, FINAL_MESSAGE_HANDOFF_MS, RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildRuntimeCardOutcome, buildRuntimeInputOutcome, initRTDBAuth, isChunkedSendMessageError, isPendingCanonOperation, normalizeRuntimeCommandDescriptors, normalizeTurnMetadata, normalizeTurnVerbosityConversationType, reportNoReplyOutcome, hydrateCanonReplyContext, resolveRuntimeProvenance, resolveTurnVerbosity, resolveConversationPolicyScope, selectInboundSelfContexts, renderCanonHostInboundContent, resolveCanonRuntimeConnection, sendMessageWithRetryChunked, shouldPublishTurnTrail, splitTextByUtf8Bytes, verifyCanonRuntimeConnection, } from '@canonmsg/core';
-import { createHash, randomUUID } from 'node:crypto';
-import { Debouncer } from './debouncer.js';
-import { disposeInboundHandoffs, selectInboundHandoffs } from './inbound-handoff.js';
-import { DEFAULT_RUNTIME_INPUT_TIMEOUT_MS, RUNTIME_INPUT_ID_PATTERN, buildRuntimeCardCreateArgs, normalizeResponseUserId, resolveRuntimeCardRouting, } from './runtime-card.js';
-import { materializeMessageMedia, materializeReplyContextMedia, sendMediaFileMessage, uploadMediaFile, } from './media.js';
-import { SessionManager } from './session-manager.js';
-import { buildTurnStreamingRequest } from './turn-streaming-request.js';
-import { selectConfiguredTurnVerbosity } from './turn-verbosity-option.js';
-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 SDK_MESSAGE_ID_READABLE_MAX = 120;
-/** Canon's message id ceiling, matching core's chunked sender. */
-const CANON_MESSAGE_ID_MAX = 160;
-const SDK_PARTIAL_FINAL_NOTICE = 'This reply stops short because Canon could not deliver the remaining text.';
-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 knownMembershipRevision(value) {
-    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
-}
-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()}`;
-}
-/**
- * Part id for text this sdk split itself, mirroring the `-part-N` rule (and the
- * 160-character id cap) that core's chunked sender applies to a split final, so
- * a caller-supplied id yields the same shape whichever path the text took.
- * Undefined base id in, undefined out: the server then names the parts.
- */
-function chunkPartMessageId(baseMessageId, part) {
-    if (!baseMessageId)
-        return undefined;
-    const suffix = `-part-${part}`;
-    return `${baseMessageId.slice(0, Math.max(0, CANON_MESSAGE_ID_MAX - suffix.length))}${suffix}`;
-}
-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);
-}
-function linkAbortSignals(turnSignal, requestSignal) {
-    if (!requestSignal || requestSignal === turnSignal) {
-        return { signal: turnSignal, dispose: () => { } };
-    }
-    const controller = new AbortController();
-    const abortFrom = (source) => {
-        if (!controller.signal.aborted)
-            controller.abort(source.reason);
-    };
-    const onTurnAbort = () => abortFrom(turnSignal);
-    const onRequestAbort = () => abortFrom(requestSignal);
-    if (turnSignal.aborted)
-        abortFrom(turnSignal);
-    else
-        turnSignal.addEventListener('abort', onTurnAbort, { once: true });
-    if (requestSignal.aborted)
-        abortFrom(requestSignal);
-    else
-        requestSignal.addEventListener('abort', onRequestAbort, { once: true });
-    return {
-        signal: controller.signal,
-        dispose: () => {
-            turnSignal.removeEventListener('abort', onTurnAbort);
-            requestSignal.removeEventListener('abort', onRequestAbort);
-        },
-    };
-}
-export class CanonAgent {
-    options;
-    runtimeConnection;
-    apiClient;
-    debouncer;
-    realtimeManager = null;
-    sessionManager = null;
-    handler = null;
-    contactAddedHandler = null;
-    contactRemovedHandler = null;
-    messageUpdatedHandler = null;
-    participationSuppressedHandler = null;
-    interruptHandler = null;
-    stopAndDropHandler = null;
-    newSessionHandler = null;
-    callStartedHandler = null;
-    callEndedHandler = null;
-    /** Whether the live SSE stream was opened with the voice family attached. */
-    voiceEventsEnabled = false;
-    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;
-    /** Discoverable Canon agents that can be selected for a later communication action. */
-    directory;
-    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;
-    startPromise = null;
-    stopPromise = null;
-    lifecycleGeneration = 0;
-    runtimeHeartbeat = null;
-    runtimeStatePublisher = null;
-    rtdbHandle = null;
-    controlPoller = null;
-    activeInbound = new Map();
-    activeAbortControllers = new Map();
-    activeTurns = new Map();
-    conversationMemberIds = new Map();
-    conversationMembershipRevisions = new Map();
-    pendingMembershipChanges = new Map();
-    typingSignals;
-    sseConnectedLogged = false;
-    constructor(options) {
-        this.runtimeConnection = resolveCanonRuntimeConnection({
-            environmentId: options.environmentId,
-            apiBaseUrl: options.baseUrl,
-            streamUrl: options.streamUrl,
-            rtdbUrl: options.rtdbUrl,
-            firebaseWebApiKey: options.firebaseApiKey,
-        });
-        this.options = {
-            deliveryMode: 'auto',
-            debounceMs: 2000,
-            historyLimit: 50,
-            autoMarkRead: true,
-            runtimeControlSurface: 'agent',
-            endpoint: {},
-            ...options,
-            environmentId: this.runtimeConnection.environmentId,
-            baseUrl: this.runtimeConnection.apiBaseUrl,
-            streamUrl: this.runtimeConnection.streamUrl,
-            rtdbUrl: this.runtimeConnection.rtdbUrl,
-            firebaseApiKey: this.runtimeConnection.firebaseWebApiKey,
-        };
-        this.apiClient = new CanonClient(this.options.apiKey, this.options.baseUrl, {
-            environmentId: this.runtimeConnection.environmentId, streamUrl: this.runtimeConnection.streamUrl, ...options.endpoint,
-        });
-        this.typingSignals = createTypingStatusPublisher({
-            setTyping: (conversationId, typing, status) => status
-                ? this.apiClient.setTyping(conversationId, typing, status)
-                : this.apiClient.setTyping(conversationId, typing),
-        });
-        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),
-        };
-        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));
-            },
-            page: (options) => apiClient.getConversationsPage(options),
-        };
-        this.directory = {
-            search: (input) => apiClient.discoverAgents(input),
-        };
-        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 === 'callStarted' || event === 'callEnded') {
-            // The voice SSE family is negotiated at connect from handler presence,
-            // so call handlers registered after start() would never fire.
-            if (this.running && !this.voiceEventsEnabled) {
-                console.warn('[canon-sdk] on(%s) registered after connect: the voice event family was not requested at stream start, so call events will not arrive until the agent restarts. Register call handlers before start().', event);
-            }
-            if (event === 'callStarted') {
-                this.callStartedHandler = handler;
-            }
-            else {
-                this.callEndedHandler = handler;
-            }
-            return;
-        }
-        if (event === 'message') {
-            this.handler = handler;
-            return;
-        }
-        if (event === 'messageUpdated') {
-            this.messageUpdatedHandler = handler;
-            return;
-        }
-        if (event === 'contactAdded') {
-            this.contactAddedHandler = handler;
-            return;
-        }
-        if (event === 'participationSuppressed') {
-            this.participationSuppressedHandler = handler;
-            return;
-        }
-        if (event === 'interrupt') {
-            this.interruptHandler = handler;
-            if (this.running) {
-                void this.baselineAndStartRuntimeControlPolling().catch(() => { });
-            }
-            this.runtimeHeartbeat?.refresh();
-            return;
-        }
-        if (event === 'stopAndDrop') {
-            this.stopAndDropHandler = handler;
-            if (this.running) {
-                void this.baselineAndStartRuntimeControlPolling().catch(() => { });
-            }
-            this.runtimeHeartbeat?.refresh();
-            return;
-        }
-        if (event === 'newSession') {
-            this.newSessionHandler = handler;
-            if (this.running) {
-                void this.baselineAndStartRuntimeControlPolling().catch(() => { });
-            }
-            this.runtimeHeartbeat?.refresh();
-            return;
-        }
-        this.contactRemovedHandler = handler;
-    }
-    onPrimitive(primitive, handler) {
-        if (primitive === '*') {
-            this.primitiveFallbackHandler = handler;
-        }
-        else {
-            this.primitiveHandlers.set(primitive, handler);
-        }
-        if (this.running) {
-            this.startRuntimeControlPolling();
-        }
-        this.runtimeHeartbeat?.refresh();
-    }
-    describeCommands() {
-        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);
-    }
-    /**
-     * Message an existing Canon conversation or start/continue a direct one.
-     * Policy and admission are enforced by Canon; this method deliberately
-     * exposes no runtime configuration or trusted source-context fields.
-     */
-    async communicate(input) {
-        return this.apiClient.communicate(input);
-    }
-    start() {
-        if (this.stopPromise)
-            return this.stopPromise.then(() => this.start());
-        if (this.startPromise)
-            return this.startPromise;
-        if (this.running)
-            return Promise.resolve();
-        const generation = ++this.lifecycleGeneration;
-        const startup = this.startRuntime(generation).catch(async (error) => {
-            if (generation === this.lifecycleGeneration) {
-                this.running = false;
-                await this.cleanupRuntime();
-            }
-            throw error;
-        });
-        this.startPromise = startup;
-        const clearStartup = () => {
-            if (this.startPromise === startup)
-                this.startPromise = null;
-        };
-        void startup.then(clearStartup, clearStartup);
-        return startup;
-    }
-    async startRuntime(generation) {
-        await verifyCanonRuntimeConnection(this.runtimeConnection);
-        if (generation !== this.lifecycleGeneration)
-            return;
-        this.running = true;
-        if (this.options.sessions?.enabled && !this.sessionManager) {
-            this.sessionManager = new SessionManager(this.options.sessions);
-        }
-        // One scoped endpoint-backed runtime-state handle per agent. Control
-        // pollers and publishers thread it through this agent's CanonClient;
-        // there is no direct RTDB connection or module-global fallback.
-        this.rtdbHandle = initRTDBAuth(this.apiClient, {
-            rtdbUrl: this.runtimeConnection.rtdbUrl,
-            firebaseApiKey: this.runtimeConnection.firebaseWebApiKey,
-        });
-        // Identity lookup only. Runtime state uses the endpoint-backed handle;
-        // the SSE stream authenticates with the API key.
-        const { agentId } = await this.apiClient.getAuthToken();
-        if (generation !== this.lifecycleGeneration)
-            return;
-        this.agentId = agentId;
-        this.runtimeHeartbeat = createRuntimeHeartbeat({
-            publisher: this.requireRuntimeStatePublisher(),
-            getRuntime: () => ({ runtimeDescriptor: this.buildRuntimeDescriptor() }),
-            onError: (error, operation) => {
-                console.error(`[canon-sdk] Runtime heartbeat ${operation} failed:`, error);
-            },
-        });
-        console.log(`[canon-sdk] Authenticated as ${agentId}`);
-        // 2. Wire debouncer to handler
-        this.debouncer.setCallback(async (conversationId, messages, provenanceByMessageId, handoffs) => {
-            this.rememberConversationId(conversationId);
-            await this.handleMessages(conversationId, messages, provenanceByMessageId, handoffs);
-        });
-        // 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
-        }
-        if (generation !== this.lifecycleGeneration)
-            return;
-        // 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');
-        }
-        if (generation !== this.lifecycleGeneration)
-            return;
-        // 3c. Initialize RTDB session state reporting (opt-in)
-        if (this.options.sessionState) {
-            const runtimeState = this.createRuntimeStatePublisher();
-            await Promise.all(this.cachedConversationIds.map((id) => (runtimeState?.writeSessionState(id, {
-                isActive: true,
-                ...(this.options.clientType ? { clientType: this.options.clientType } : {}),
-            }).catch(() => { }))));
-            if (generation !== this.lifecycleGeneration)
-                return;
-            if (this.cachedConversationIds.length > 0) {
-                console.log(`[canon-sdk] Session state reported for ${this.cachedConversationIds.length} conversations`);
-            }
-        }
-        await this.baselineRuntimeControlSignals(this.cachedConversationIds);
-        if (generation !== this.lifecycleGeneration)
-            return;
-        this.startRuntimeControlPolling();
-        // 4. Start delivery
-        const { RealtimeManager } = await import('./realtime.js');
-        if (generation !== this.lifecycleGeneration)
-            return;
-        this.voiceEventsEnabled = Boolean(this.callStartedHandler || this.callEndedHandler);
-        const rtm = new RealtimeManager(this.options.apiKey, this.debouncer, agentId, this.options.streamUrl, { enableVoiceEvents: this.voiceEventsEnabled, endpoint: await this.apiClient.getEndpoint() });
-        if (this.voiceEventsEnabled) {
-            rtm.setCallHandlers({
-                onCallStarted: (payload) => {
-                    void Promise.resolve(this.callStartedHandler?.(payload)).catch((error) => {
-                        console.error('[canon-sdk] callStarted handler failed:', error);
-                    });
-                },
-                onCallEnded: (payload) => {
-                    void Promise.resolve(this.callEndedHandler?.(payload)).catch((error) => {
-                        console.error('[canon-sdk] callEnded handler failed:', error);
-                    });
-                },
-            });
-        }
-        rtm.setOnAgentContext((ctx) => {
-            this.agentContext = ctx;
-            this.ensureApprovalManager(ctx);
-        });
-        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.setParticipationSuppressedHandler((payload) => {
-            // Observe-only by construction: this path never touches the debouncer,
-            // the message handler, or the turn pipeline.
-            void this.handleParticipationSuppressedEvent(payload);
-        });
-        rtm.setMessageUpdatedHandler((payload) => {
-            void this.handleMessageUpdatedEvent(payload);
-        });
-        rtm.setMessageDeletedHandler((payload) => {
-            this.sessionManager?.dropQueuedMessage(payload.conversationId, payload.messageId);
-            for (const handoffs of this.activeInbound.get(payload.conversationId) ?? []) {
-                void disposeInboundHandoffs(selectInboundHandoffs(handoffs, [payload.messageId]), 'cancel', 'message-deleted');
-            }
-        });
-        rtm.setConnectionHandlers({
-            onConnected: () => {
-                if (!this.running || generation !== this.lifecycleGeneration)
-                    return;
-                this.runtimeHeartbeat?.connect();
-                if (!this.sseConnectedLogged) {
-                    this.sseConnectedLogged = true;
-                    console.log('[canon-sdk] SSE stream connected');
-                }
-            },
-            onDisconnected: () => {
-                if (generation === this.lifecycleGeneration) {
-                    void this.runtimeHeartbeat?.disconnect();
-                }
-            },
-        });
-        this.realtimeManager = rtm;
-        await rtm.start();
-        if (generation !== this.lifecycleGeneration)
-            rtm.stop();
-    }
-    async createGroup(options) {
-        return this.apiClient.createGroup(options);
-    }
-    // ── Calls ────────────────────────────────────────────────────────────
-    // These return the LiveKit room token payload; the agent brings its own
-    // RTC transport (e.g. @livekit/rtc-node as an optional, lazily imported
-    // dependency — the openclaw voice bridge is the reference implementation).
-    /** Start (or rejoin) a call in a conversation and get the room token. */
-    async startCall(options) {
-        return this.apiClient.createVoiceSession(options);
-    }
-    /** Join an active call session and get the room token. */
-    async joinCall(conversationId, sessionId) {
-        return this.apiClient.joinVoiceSession(conversationId, sessionId);
-    }
-    /** Decline an incoming call: stops this agent's ring only. */
-    async declineCall(conversationId, sessionId) {
-        return this.apiClient.declineVoiceSession(conversationId, sessionId);
-    }
-    /** End an active call session for everyone. */
-    async endCall(conversationId, sessionId) {
-        return this.apiClient.endVoiceSession(conversationId, sessionId);
-    }
-    /** Fetch the current state of a call session. */
-    async getCallState(conversationId, sessionId) {
-        const result = await this.apiClient.getVoiceSessionState(conversationId, sessionId);
-        return result.session;
-    }
-    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 needs policy approval.
-     *   The server created one `group_invite`; membership activates after approval
-     *   The approved membership arrives through the normal conversation update.
-     *
-     * Throws `CanonApiError` for hard failures (block, inactive, closed policy,
-     * 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 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 handleParticipationSuppressedEvent(payload) {
-        if (!this.participationSuppressedHandler)
-            return;
-        try {
-            await this.participationSuppressedHandler(payload);
-        }
-        catch (error) {
-            console.error('[canon-sdk] participationSuppressed 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);
-        }
-    }
-    stop() {
-        if (this.stopPromise)
-            return this.stopPromise;
-        if (!this.running && !this.startPromise)
-            return Promise.resolve();
-        ++this.lifecycleGeneration;
-        this.running = false;
-        this.stopRuntimeControlPolling();
-        this.realtimeManager?.stop();
-        void this.runtimeHeartbeat?.disconnect();
-        const startup = this.startPromise;
-        const stopping = (async () => {
-            // Startup checks the generation after each await, so it cannot install
-            // new resources after this shutdown or a subsequent start.
-            await startup?.catch(() => { });
-            await this.cleanupRuntime();
-            console.log('[canon-sdk] Stopped');
-        })();
-        this.stopPromise = stopping;
-        const clearStopping = () => {
-            if (this.stopPromise === stopping)
-                this.stopPromise = null;
-        };
-        void stopping.then(clearStopping, clearStopping);
-        return stopping;
-    }
-    async cleanupRuntime() {
-        this.stopRuntimeControlPolling();
-        this.controlPoller = null;
-        this.realtimeManager?.stop();
-        this.realtimeManager = null;
-        this.debouncer.destroy();
-        for (const batches of this.activeInbound.values()) {
-            for (const handoffs of batches)
-                void disposeInboundHandoffs(handoffs, 'release', 'runtime-closed');
-        }
-        this.sessionManager?.destroy();
-        this.sessionManager = null;
-        const heartbeat = this.runtimeHeartbeat;
-        this.runtimeHeartbeat = null;
-        await heartbeat?.dispose();
-        // Startup awaits its initial session writes, so they finish before these
-        // clears. Already-running message handlers keep their existing lifecycle.
-        const runtimeState = this.runtimeStatePublisher;
-        if (runtimeState) {
-            await Promise.all(this.cachedConversationIds.flatMap((id) => [
-                runtimeState.clearTurnState(id).catch(() => { }),
-                ...(this.options.sessionState ? [runtimeState.clearSessionState(id).catch(() => { })] : []),
-            ]));
-        }
-        this.runtimeStatePublisher = null;
-        this.rtdbHandle = null;
-        this.agentId = null;
-        this.agentContext = null;
-        this.cachedConversationIds = [];
-        this.sseConnectedLogged = false;
-    }
-    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),
-        };
-    }
-    rememberConversationId(conversationId) {
-        if (this.cachedConversationIds.includes(conversationId))
-            return;
-        this.cachedConversationIds.push(conversationId);
-    }
-    rememberConversationMembers(conversations) {
-        for (const conversation of conversations) {
-            const revision = knownMembershipRevision(conversation.membershipRevision);
-            const currentRevision = this.conversationMembershipRevisions.get(conversation.id);
-            if (revision !== undefined && currentRevision !== undefined && revision < currentRevision)
-                continue;
-            this.conversationMemberIds.set(conversation.id, [...(conversation.memberIds ?? [])]);
-            if (revision !== undefined)
-                this.conversationMembershipRevisions.set(conversation.id, revision);
-            else
-                this.conversationMembershipRevisions.delete(conversation.id);
-        }
-    }
-    handleConversationUpdated(payload) {
-        const rawMemberIds = payload.changes.memberIds;
-        if (!Array.isArray(rawMemberIds))
-            return;
-        const revision = knownMembershipRevision(payload.changes.membershipRevision);
-        const currentRevision = this.conversationMembershipRevisions.get(payload.conversationId);
-        if (revision !== undefined && currentRevision !== undefined && revision < currentRevision)
-            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 (revision !== undefined)
-            this.conversationMembershipRevisions.set(payload.conversationId, revision);
-        else
-            this.conversationMembershipRevisions.delete(payload.conversationId);
-        if (membershipChange) {
-            this.pendingMembershipChanges.set(payload.conversationId, membershipChange);
-        }
-        if (this.agentId && !memberIds.includes(this.agentId)) {
-            this.cachedConversationIds = this.cachedConversationIds.filter((id) => id !== payload.conversationId);
-            this.abortActiveTurns(payload.conversationId, false);
-            this.debouncer.dropConversation(payload.conversationId);
-            this.sessionManager?.dropQueued(payload.conversationId);
-            this.pendingMembershipChanges.delete(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);
-    }
-    async baselineAndStartRuntimeControlPolling() {
-        const generation = this.lifecycleGeneration;
-        await this.baselineRuntimeControlSignals(this.cachedConversationIds);
-        if (this.running && generation === this.lifecycleGeneration) {
-            this.startRuntimeControlPolling();
-        }
-    }
-    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 debouncedMessages = signal === 'new_session' || signal === 'stop_and_drop'
-            ? this.debouncer.dropConversation(conversationId) : [];
-        const sessionMessages = signal === 'new_session'
-            ? this.sessionManager?.resetSession(conversationId) ?? []
-            : signal === 'stop_and_drop'
-                ? this.sessionManager?.dropQueued(conversationId) ?? []
-                : [];
-        const droppedMessages = [...debouncedMessages, ...sessionMessages];
-        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, cancelPreparing = true) {
-        // Membership snapshots may arrive while a newer authoritative refresh is
-        // pending. Only explicit controls discard those still-preparing inputs.
-        for (const handoffs of cancelPreparing ? this.activeInbound.get(conversationId) ?? [] : []) {
-            void disposeInboundHandoffs(handoffs, 'cancel', 'turn-canceled-before-submit');
-        }
-        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,
-     * endpoint-backed handle (captured in start()). The publisher requires
-     * that handle, so each agent uses its own CanonClient credentials.
-     */
-    createRuntimeStatePublisher() {
-        if (!this.agentId)
-            return null;
-        // start() assigns rtdbHandle before agentId, so this can only be null
-        // when the agent has not started — same condition as the guard above.
-        if (!this.rtdbHandle)
-            return null;
-        this.runtimeStatePublisher ??= createRuntimeStatePublisher({
-            agentId: this.agentId,
-            clientType: this.options.clientType ?? 'generic',
-            hostMode: this.options.runtimeControlSurface === 'host',
-            rtdb: this.rtdbHandle,
-        });
-        return this.runtimeStatePublisher;
-    }
-    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, handoffs = new Map()) {
-        const actionableMessages = this.filterApprovalReplyMessages(conversationId, messages);
-        const consumed = messages.filter((message) => !actionableMessages.includes(message));
-        void disposeInboundHandoffs(selectInboundHandoffs(handoffs, consumed.map((message) => message.id)), 'cancel', 'interaction-consumed');
-        if (actionableMessages.length === 0)
-            return;
-        messages = actionableMessages;
-        handoffs = selectInboundHandoffs(handoffs, messages.map((message) => message.id));
-        if (!this.handler) {
-            await disposeInboundHandoffs(handoffs, 'release', 'no-handler');
-            console.warn(`[canon-sdk] No message handler registered — input for ${conversationId} is deferred. 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;
-        const notification = this.notifyMessageInterrupt(conversationId, abortSignal);
-        if (this.sessionManager) {
-            await this.sessionManager.enqueue(conversationId, messages, async (session, newMessages, batchHandoffs) => {
-                await this.executeHandler(conversationId, newMessages, session, provenanceByMessageId, batchHandoffs, notification);
-            }, { toFront: shouldInterrupt, handoffs });
-        }
-        else {
-            await this.executeHandler(conversationId, messages, undefined, provenanceByMessageId, handoffs, notification);
-        }
-    }
-    async executeHandler(conversationId, messages, session, provenanceByMessageId, handoffs = new Map(), notification) {
-        const batches = this.activeInbound.get(conversationId) ?? new Set();
-        batches.add(handoffs);
-        this.activeInbound.set(conversationId, batches);
-        try {
-            await notification;
-            await this.executeOwnedHandler(conversationId, messages, session, provenanceByMessageId, handoffs);
-        }
-        finally {
-            batches.delete(handoffs);
-            if (batches.size === 0)
-                this.activeInbound.delete(conversationId);
-            // Queued/deferred inputs go back to the engine's durable retry loop.
-            // Submitted effects cannot be released: failures remain uncertain.
-            await disposeInboundHandoffs(handoffs, 'release', 'sdk-batch-finished');
-        }
-    }
-    async executeOwnedHandler(conversationId, messages, session, provenanceByMessageId, handoffs) {
-        if (!this.handler || messages.length === 0 || handoffs.size !== messages.length
-            || [...handoffs.values()].some((handoff) => handoff.phase !== 'queued'))
-            return;
-        // Refresh admission before freezing output policy or constructing context.
-        const endpoint = await this.apiClient.getEndpoint();
-        const cancelInputs = (reason) => disposeInboundHandoffs(handoffs, 'cancel', reason);
-        let conversation;
-        try {
-            conversation = await this.apiClient.getConversation(conversationId);
-        }
-        catch (error) {
-            console.error(`[canon-sdk] Input deferred until conversation refresh recovers for ${conversationId}:`, error);
-            return;
-        }
-        if (!conversation) {
-            await cancelInputs('conversation-unavailable');
-            return;
-        }
-        this.rememberConversationMembers([conversation]);
-        const currentMembers = this.conversationMemberIds.get(conversationId);
-        if (currentMembers && this.agentId && !currentMembers.includes(this.agentId)) {
-            await cancelInputs('membership-lost');
-            return;
-        }
-        this.rememberConversationId(conversationId);
-        await this.markQueuedMessagesAccepted(conversationId, messages);
-        const acceptedMembers = this.conversationMemberIds.get(conversationId);
-        if (acceptedMembers && this.agentId && !acceptedMembers.includes(this.agentId)) {
-            await cancelInputs('membership-lost');
-            return;
-        }
-        const turnId = randomUUID();
-        const turnOpenedAt = Date.now();
-        let turnState = 'thinking';
-        let shouldPersistTurnState = false;
-        // `ctx.turn.noReply()`: the handler chose to end this turn without posting.
-        // Governs TEARDOWN only — `replyFinal` still sends, because in the SDK the
-        // developer's two explicit calls are two explicit decisions.
-        let deliberatelySilent = false;
-        // The FIRST noReply call's reason (one silence decision per turn), carried
-        // to teardown where the outcome report fires. Only its presence rides the
-        // wire — see reportNoReplyOutcome's sentinel.
-        let noReplyReason;
-        // Set when the handler threw or the turn was aborted. Deliberate silence
-        // must never blank the live node on those paths: the streamed content is
-        // all that survives a turn that died mid-flight.
-        let turnEndedAbnormally = false;
-        let durableMessageSequence = 0;
-        // The freshest message in the batch is the turn's trigger — same convention
-        // as the provenance lookup for turn verbosity below.
-        const triggeringMessageId = messages[messages.length - 1]?.id;
-        const triggeringReplyAuthority = messages[messages.length - 1]?.replyAuthority;
-        const agentId = this.agentId;
-        const runtimeState = this.createRuntimeStatePublisher();
-        const queueDepth = () => this.sessionManager?.getQueueDepth(conversationId) ?? 0;
-        const abortController = new AbortController();
-        abortController.signal.addEventListener('abort', () => {
-            void disposeInboundHandoffs(handoffs, 'cancel', 'turn-canceled-before-submit');
-        }, { once: true });
-        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(() => { });
-        };
-        // Resolve once from the refreshed roster before constructing the output
-        // controller or publishing the first thinking seed. Keep it fixed for the
-        // turn so the final trail agrees with what was actually narrated.
-        const inboundProvenance = provenanceByMessageId?.get(triggeringMessageId ?? '')?.conversation;
-        const inboundRoster = this.conversationMemberIds.get(conversationId) ?? inboundProvenance?.memberCount;
-        const inboundConversationType = inboundRoster != null
-            ? resolveConversationPolicyScope(inboundRoster)
-            : normalizeTurnVerbosityConversationType(inboundProvenance?.type);
-        const turnVerbosity = resolveTurnVerbosity({
-            configured: selectConfiguredTurnVerbosity(this.options.turnVerbosity, inboundConversationType),
-            conversationType: inboundConversationType,
-        });
-        const turnOutput = createTurnOutputController({
-            turnId,
-            // `'status'` keeps every controller call site working and drops only the
-            // RTDB write, which covers all ~12 of them at once — the thinking seed
-            // and its keepalive, `turn.appendDelta`/`appendBlock`/`setTool`, the
-            // approval block, and `replyProgress`'s implicit live half. Blocks still
-            // accumulate in memory, so the trail gate below is a SEPARATE decision.
-            mode: turnVerbosity === 'quiet' ? 'status' : 'snapshot',
-            writeSnapshot: (snapshot) => this.apiClient.setStreaming(buildTurnStreamingRequest({ conversationId, snapshot })),
-            clearSnapshot: () => this.apiClient.clearStreaming(conversationId),
-        });
-        const setLiveState = async (state, text, streamingStatus) => {
-            throwIfAborted();
-            await writeTurn(state);
-            if (streamingStatus) {
-                await turnOutput.setStatus(streamingStatus, text ?? '');
-            }
-        };
-        /**
-         * Put the turn back to work after an interaction request settles.
-         *
-         * Both halves matter: the dots were cleared when the turn parked (the
-         * clients suppress an agent's dots on `waiting_input`), and `/turn-state`
-         * plus the live node are still sitting on `waiting_input`. The error paths
-         * need this as much as the success paths — a request that failed still
-         * leaves the handler running, and a quiet turn has no live row to stand in
-         * for the missing dots. Aborts still propagate: `setLiveState` re-checks
-         * the signal, which is how an interrupt lands during cleanup.
-         */
-        const resumeTurnFromWaiting = async () => {
-            try {
-                await this.typingSignals.start(conversationId, 'thinking');
-            }
-            catch { }
-            await setLiveState('thinking', 'Thinking...', 'thinking');
-        };
-        if (turnVerbosity === 'quiet') {
-            // A quiet turn never writes to `/streaming`, so it cannot rely on the
-            // 'Thinking...' seed below to overwrite a node an earlier verbose turn
-            // left behind — and a surviving node under the PREVIOUS turn's id would
-            // sit there, invisible, for this whole turn, then be deleted at teardown:
-            // `onStreamingCleared` would salvage it into a durable bubble landing
-            // AFTER this turn's answer. Deleting at turn open puts that salvage back
-            // where the design intends it, ahead of the answer. Both coding hosts do
-            // the same, one for free (its seed clears unconditionally) and one
-            // explicitly.
-            await turnOutput.clear().catch(() => { });
-        }
-        // 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);
-            }
-            // Build reply functions
-            const replyFinal = async (text, options, delivery) => {
-                throwIfAborted();
-                try {
-                    await this.typingSignals.start(conversationId, 'typing');
-                }
-                catch { }
-                throwIfAborted();
-                const sendOptions = withActiveSelfContext(options);
-                // Separate from the controller's mode on purpose: `'status'` silences
-                // the live writes but still accumulates blocks, so `getFinalTrail()`
-                // would happily hand back a full trail for a turn that narrated
-                // nothing.
-                const turnTrail = shouldPublishTurnTrail(turnVerbosity) ? turnOutput.getFinalTrail() : [];
-                const finalOptions = {
-                    ...sendOptions,
-                    metadata: {
-                        ...(sendOptions.metadata ?? {}),
-                        turnId,
-                        turnSemantics: 'turn_complete',
-                        ...(turnTrail.length > 0 ? { turnTrail } : {}),
-                    },
-                };
-                let result;
-                try {
-                    result = await sendDurableMessage(text, finalOptions, ['sdk', 'final', conversationId, turnId], delivery);
-                }
-                catch (error) {
-                    const chunked = isChunkedSendMessageError(error) ? error : null;
-                    if (!chunked || chunked.deliveredMessageIds.length === 0 || sendOptions.messageId || isAbortLikeError(error) || isPendingCanonOperation(error)) {
-                        throw error;
-                    }
-                    const requestedReplyBehavior = sendOptions.metadata?.replyBehavior;
-                    const notice = await sendDurableMessage(SDK_PARTIAL_FINAL_NOTICE, {
-                        ...sendOptions,
-                        messageId: buildSdkMessageId(['sdk', 'final-incomplete', conversationId, turnId]),
-                        metadata: {
-                            turnId,
-                            turnSemantics: 'turn_complete',
-                            ...(requestedReplyBehavior ? { replyBehavior: requestedReplyBehavior } : {}),
-                        },
-                    }, ['sdk', 'final-incomplete', conversationId, turnId]);
-                    result = {
-                        messageId: notice.messageId,
-                        messageIds: [...chunked.deliveredMessageIds, ...notice.messageIds],
-                    };
-                }
-                await sleep(FINAL_MESSAGE_HANDOFF_MS);
-                try {
-                    await this.typingSignals.clear(conversationId);
-                }
-                catch { }
-                return result;
-            };
-            const replyProgress = async (text, options) => {
-                throwIfAborted();
-                // Owner ruling D1: in quiet the IMPLICIT half of this call — the live
-                // `/streaming` narration — is dropped by the controller's `'status'`
-                // mode, while the turn state it also publishes stays. The EXPLICIT half
-                // below does not: `durable: true` is a developer asking Canon to post a
-                // message, structurally the same act as `replyFinal`, and silently
-                // no-op'ing it would leave a caller reading `durable: true` from a send
-                // that never happened. The result object therefore keeps describing
-                // what actually occurred in both modes.
-                await setLiveState('streaming', text, 'streaming');
-                if (!options?.durable) {
-                    return { turnId, durable: false, messageId: null };
-                }
-                throwIfAborted();
-                // Durable progress skips `sendDurableMessage` (see the chunking note
-                // below) but it is still a durable message in the timeline, so it must
-                // advance the same counter teardown reads for the silence report.
-                durableMessageSequence += 1;
-                const { durable: _durable, ...sendOptions } = options;
-                const sendOptionsWithContext = withActiveSelfContext(sendOptions);
-                // Progress text is caller-controlled too, so it can also blow past
-                // Canon's 4 KB cap. It is split here rather than through core's chunked
-                // sender on purpose: chunk parts carry a `messageChunk` marker, and
-                // Canon clients read a progress message that has one as durable answer
-                // content (chat-domain's `isEphemeralProgressMessage`). Routing progress
-                // through the chunked sender would therefore leave an oversized status
-                // update in the timeline forever, while the same update under the cap is
-                // folded into the turn trail once the turn ends. Plain progress parts
-                // keep long and short updates behaving identically, and each part stays
-                // a single unretried send, exactly as one progress update always was.
-                const parts = splitTextByUtf8Bytes(text);
-                const messageIds = [];
-                for (const [index, part] of parts.entries()) {
-                    throwIfAborted();
-                    const partMessageId = parts.length > 1
-                        ? chunkPartMessageId(sendOptionsWithContext.messageId, index + 1)
-                        : sendOptionsWithContext.messageId;
-                    const result = await this.apiClient.sendMessage(conversationId, part, {
-                        ...sendOptionsWithContext,
-                        ...(partMessageId !== undefined ? { messageId: partMessageId } : {}),
-                        metadata: {
-                            ...(sendOptionsWithContext.metadata ?? {}),
-                            turnId,
-                            turnSemantics: 'progress',
-                        },
-                    });
-                    messageIds.push(result.messageId);
-                }
-                return {
-                    turnId,
-                    durable: true,
-                    messageId: messageIds[messageIds.length - 1],
-                    messageIds,
-                };
-            };
-            // 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;
-            const triggeringHumanId = latestMessage?.senderType === 'human'
-                ? normalizeResponseUserId(latestMessage.senderId)
-                : undefined;
-            let replyContext = latestMessage
-                ? await hydrateCanonReplyContext({
-                    client: this.apiClient, conversationId, message: latestMessage, messages: history,
-                })
-                : null;
-            const selectedSelfContext = selectInboundSelfContexts({
-                selfContexts: page.selfContexts,
-                replyTo: latestMessage?.replyTo,
-                linkedSelfContextId: latestMessage?.id
-                    ? page.activeSelfContextIdByMessageId?.[latestMessage.id]
-                    : null,
-                messages: page.messages,
-                replyContext,
-            });
-            const selfContexts = selectedSelfContext.selfContexts;
-            const activeSelfContextId = selectedSelfContext.activeSelfContextId;
-            const withActiveSelfContext = (options) => {
-                const base = { ...(options ?? {}) };
-                const withContext = base.selfContextId !== undefined || !activeSelfContextId
-                    ? base
-                    : { ...base, selfContextId: activeSelfContextId };
-                return withContext.replyAuthority !== undefined || !triggeringReplyAuthority
-                    ? withContext
-                    : { ...withContext, replyAuthority: triggeringReplyAuthority };
-            };
-            // Core's chunked sender walks the parts in a plain loop and knows nothing
-            // about this turn's abort signal, so a stop landing after part 1 would
-            // otherwise let the rest of the answer post anyway — including the last
-            // part, which completes the turn. Sending every part through a client that
-            // re-checks the signal first is the sdk-side guard for that; the `sleep`
-            // override below only covers a retry backoff.
-            const abortAwareClient = Object.create(this.apiClient, {
-                sendMessage: {
-                    value: (targetConversationId, targetText, targetOptions, delivery) => {
-                        throwIfAborted();
-                        return delivery?.operationId
-                            ? this.apiClient.sendMessage(targetConversationId, targetText, targetOptions, delivery)
-                            : this.apiClient.sendMessage(targetConversationId, targetText, targetOptions);
-                    },
-                },
-            });
-            // Canon rejects any message whose text is over 4 KB of UTF-8 with a 400,
-            // which no retry can fix — an oversized reply used to throw out of the
-            // handler with nothing durable written, so a long answer just vanished.
-            // Core's chunked sender splits such a reply into ordered `-part-N`
-            // messages instead, completing the turn on the last part only. A reply
-            // that FITS still goes out as a single message under the plain id with
-            // untouched metadata, so the common case (and the interim→final handoff
-            // that keys on that id) is unchanged.
-            const sendDurableMessage = async (text, options, fallbackMessageIdParts, delivery) => {
-                // Counts every durable send the turn attempts, not just the ones that
-                // needed a generated id: teardown reads `durableMessageSequence` to
-                // decide whether the turn genuinely ended silent, and a reply sent
-                // under an explicit caller messageId must not look like silence.
-                durableMessageSequence += 1;
-                const messageId = options?.messageId
-                    ?? buildSdkMessageId([...fallbackMessageIdParts, durableMessageSequence]);
-                const { messageIds } = await sendMessageWithRetryChunked(abortAwareClient, conversationId, text, {
-                    ...(options ?? {}),
-                    messageId,
-                }, {
-                    signal: abortController.signal,
-                    ...(delivery?.operationId ? { operationId: delivery.operationId } : {}),
-                    ...(delivery?.replacesOperationId ? { replacesOperationId: delivery.replacesOperationId } : {}),
-                }, {
-                    resumable: true,
-                });
-                // `messageId` stays the single id callers expect. When the text was
-                // chunked it points at the LAST part — the message that carries
-                // turn_complete and the turn trail, so replies and reactions thread off
-                // the end of the answer, not its head. `messageIds` has the full set.
-                return { messageId: messageIds[messageIds.length - 1], messageIds };
-            };
-            // Runtime context must come from authenticated agent metadata. A synthetic
-            // generation cannot authorize an endpoint or a new owner's native work.
-            const agent = this.agentContext ?? await this.apiClient.getAgentMe();
-            const provenance = latestMessage
-                ? resolveRuntimeProvenance({
-                    provenance: provenanceByMessageId?.get(latestMessage.id) ?? null,
-                    conversationId,
-                    conversationType: resolveConversationPolicyScope(conversation.memberIds),
-                    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: resolveConversationPolicyScope(conversation.memberIds),
-                    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);
-            const turnContext = buildCanonTurnContextV2({
-                content: latestMessage ? renderCanonHostInboundContent(latestMessage) : '[Empty message]',
-                conversationId,
-                participantContext: {
-                    conversationType: resolveConversationPolicyScope(conversation.memberIds),
-                    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 communicate = (input) => this.communicate(input);
-            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 responseUserId = normalizeResponseUserId(request.responseUserId)
-                        ?? triggeringHumanId;
-                    // Session-wide rules are owner-scoped. The effective responder, not
-                    // merely the member who triggered the turn, determines that scope.
-                    const mustIsolateSessionRules = Boolean(responseUserId && responseUserId !== agent.ownerId);
-                    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,
-                        ...(responseUserId ? { responseUserId } : {}),
-                        ignoreSessionRules: mustIsolateSessionRules ? true : request.ignoreSessionRules,
-                        allowSessionRule: mustIsolateSessionRules ? false : request.allowSessionRule,
-                    }, request.signal ? { signal: request.signal } : undefined);
-                    throwIfAborted();
-                    shouldPersistTurnState = false;
-                    try {
-                        await turnOutput.completeBlock(`approval:${request.runtimeId ?? request.toolName}:${turnId}`, {
-                            summary: `Decision: ${result.decision}`,
-                        });
-                    }
-                    catch { }
-                    await resumeTurnFromWaiting();
-                    return result;
-                }
-                catch (error) {
-                    if (abortController.signal.aborted || isAbortLikeError(error)) {
-                        throw error;
-                    }
-                    shouldPersistTurnState = false;
-                    // The turn parked before the request went out and the handler is
-                    // about to carry on with a denial, so put it back to work — the
-                    // success path is not the only way out of `waiting_input`.
-                    await resumeTurnFromWaiting();
-                    return { decision: 'deny' };
-                }
-            };
-            const requestRuntimeInput = async (request) => {
-                throwIfAborted();
-                const linkedSignal = linkAbortSignals(abortController.signal, request.signal);
-                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;
-                let result = { status: 'timeout', inputId };
-                let requestCreated = false;
-                const ownerOnly = request.kind === 'secret'
-                    || request.kind === 'sudo'
-                    || request.sensitive === true
-                    || Boolean(request.questions?.some((question) => question.isSecret));
-                const responseUserId = ownerOnly
-                    ? normalizeResponseUserId(agent.ownerId)
-                    : normalizeResponseUserId(request.responseUserId)
-                        ?? triggeringHumanId
-                        ?? normalizeResponseUserId(agent.ownerId);
-                shouldPersistTurnState = true;
-                try {
-                    await this.apiClient.createRuntimeInputRequest({
-                        conversationId,
-                        inputId,
-                        kind: request.kind,
-                        expiresAt: expiresAtMs,
-                        ...(responseUserId ? { responseUserId } : {}),
-                        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: linkedSignal.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 { }
-                    await resumeTurnFromWaiting();
-                    return result;
-                }
-                catch (error) {
-                    if (abortController.signal.aborted || request.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;
-                    // Parked, then failed rather than answered — the handler carries on
-                    // with the fallback result, so the turn has to look like it is
-                    // working again. The success path is not the only way out.
-                    await resumeTurnFromWaiting();
-                    return result;
-                }
-                finally {
-                    linkedSignal.dispose();
-                }
-            };
-            const requestPlanReview = async (request) => {
-                throwIfAborted();
-                const linkedSignal = linkAbortSignals(abortController.signal, request.signal);
-                const planId = request.planId && RUNTIME_INPUT_ID_PATTERN.test(request.planId)
-                    ? request.planId
-                    : randomUUID();
-                const timeoutMs = Math.max(1_000, request.timeoutMs ?? DEFAULT_RUNTIME_INPUT_TIMEOUT_MS);
-                const expiresAtMs = Date.now() + timeoutMs;
-                const responseUserId = normalizeResponseUserId(request.responseUserId)
-                    ?? triggeringHumanId
-                    ?? normalizeResponseUserId(agent.ownerId);
-                let created = false;
-                let result = { status: 'timeout', planId };
-                shouldPersistTurnState = true;
-                try {
-                    result = await this.ensureRuntimeRequestManager().request('plan', conversationId, {
-                        ...(request.title ? { title: request.title } : {}),
-                        ...(request.summary ? { summary: request.summary } : {}),
-                        ...(request.body ? { body: request.body } : {}),
-                        ...(request.allowedPrompts ? { allowedPrompts: request.allowedPrompts } : {}),
-                        ...(responseUserId ? { responseUserId } : {}),
-                        turnId: request.turnId ?? turnId,
-                    }, {
-                        requestId: planId,
-                        expiresAt: expiresAtMs,
-                        responderPolicy: 'infer',
-                        signal: linkedSignal.signal,
-                        onCreated: async () => {
-                            created = true;
-                            try {
-                                await turnOutput.addBlock({
-                                    id: `plan:${planId}`,
-                                    kind: 'input',
-                                    status: 'pending',
-                                    title: request.title ?? 'Plan review',
-                                    summary: request.summary ?? 'Review requested',
-                                });
-                                await turnOutput.waitingInput();
-                            }
-                            catch { }
-                            await writeTurn('waiting_input');
-                            try {
-                                await this.typingSignals.clear(conversationId);
-                            }
-                            catch { }
-                        },
-                    });
-                    throwIfAborted();
-                    shouldPersistTurnState = false;
-                    try {
-                        await turnOutput.completeBlock(`plan:${planId}`, {
-                            summary: `Plan ${result.status}`,
-                        });
-                    }
-                    catch { }
-                    await resumeTurnFromWaiting();
-                    return result;
-                }
-                catch (error) {
-                    if (abortController.signal.aborted || request.signal?.aborted || isAbortLikeError(error)) {
-                        throw error;
-                    }
-                    shouldPersistTurnState = false;
-                    if (!created)
-                        throw error;
-                    await resumeTurnFromWaiting();
-                    return result;
-                }
-                finally {
-                    linkedSignal.dispose();
-                }
-            };
-            const sendCard = async (request) => {
-                throwIfAborted();
-                const { cardId, expiresAtMs, routedRequest } = resolveRuntimeCardRouting({
-                    request,
-                    triggeringHumanId,
-                });
-                // 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: routedRequest,
-                    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, expiresAtMs, routedRequest } = resolveRuntimeCardRouting({
-                    request,
-                    triggeringHumanId,
-                });
-                let result = { status: 'timeout', cardId };
-                let requestCreated = false;
-                let requestResolved = false;
-                shouldPersistTurnState = true;
-                try {
-                    await this.apiClient.createRuntimeCardRequest(buildRuntimeCardCreateArgs({
-                        request: routedRequest,
-                        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 { }
-                    await resumeTurnFromWaiting();
-                    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;
-                    // Parked, then failed rather than answered — the handler carries on
-                    // with the fallback result, so the turn has to look like it is
-                    // working again. The success path is not the only way out.
-                    await resumeTurnFromWaiting();
-                    return result;
-                }
-            };
-            const uploadFile = (filePath, options) => uploadMediaFile(this.apiClient, conversationId, filePath, {
-                ...(options ?? {}),
-                signal: options?.signal ?? abortController.signal,
-            });
-            const replyWithFile = async (filePath, text = '', options) => {
-                throwIfAborted();
-                try {
-                    await this.typingSignals.start(conversationId, 'typing');
-                }
-                catch { }
-                throwIfAborted();
-                try {
-                    // Same gate as `replyFinal` — this send IS a final, trail included.
-                    const turnTrail = shouldPublishTurnTrail(turnVerbosity) ? 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 } : {}),
-                        ...(options?.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
-                        signal: options?.signal ?? abortController.signal,
-                    });
-                    durableMessageSequence += 1;
-                    await sleep(FINAL_MESSAGE_HANDOFF_MS);
-                    return result;
-                }
-                finally {
-                    try {
-                        await this.typingSignals.clear(conversationId);
-                    }
-                    catch { }
-                }
-            };
-            // The client's own room object (its "last seen" memory spans turns),
-            // made on first use so a turn that never touches shared work cannot fail
-            // on it. Arrival reads nothing on the handler's behalf: the base of a
-            // change is only what the handler itself read or wrote. Names this turn
-            // already holds spare views a member lookup.
-            let artifacts;
-            const conversationArtifacts = () => {
-                if (artifacts)
-                    return artifacts;
-                const ownerId = this.agentContext?.ownerId;
-                this.apiClient.rememberParticipantNames(conversationId, {
-                    ...(ownerId ? { [ownerId]: this.agentContext?.ownerName } : {}),
-                    ...Object.fromEntries([...history, ...hydratedMessages].flatMap((message) => message.senderName ? [[message.senderId, message.senderName]] : [])),
-                });
-                return artifacts = this.apiClient.artifacts(conversationId);
-            };
-            // Fence uncertain native/business effects before handing execution out.
-            // A crash after this write requires provider/operator reconciliation.
-            throwIfAborted();
-            const submission = await endpoint.startInbound([...handoffs.values()], () => this.handler({
-                messages: hydratedMessages,
-                history,
-                replyContext,
-                conversationId,
-                conversation,
-                ...(groupContext ? { groupContext } : {}),
-                replyFinal,
-                getReplyOperation: (messageId, delivery) => this.apiClient.getMessageOperation(conversationId, messageId, delivery),
-                waitForReply: async (operationId) => {
-                    throwIfAborted();
-                    durableMessageSequence += 1;
-                    const result = await this.apiClient.waitForOperation(operationId, { signal: abortController.signal });
-                    if (typeof result?.messageId !== 'string' || !result.messageId)
-                        throw new Error('Canon returned a malformed message receipt');
-                    try {
-                        await this.typingSignals.clear(conversationId);
-                    }
-                    catch { }
-                    return { messageId: result.messageId, messageIds: result.messageIds ?? [result.messageId] };
-                },
-                replyProgress,
-                deleteMessage,
-                markAsRead,
-                leave,
-                react,
-                addMember,
-                removeMember,
-                communicate,
-                agent,
-                activeSelfContextId,
-                selfContexts,
-                provenance,
-                turnContext,
-                // Lenient: a malformed reference is dropped, never fatal to the batch.
-                artifactContexts: hydratedMessages.flatMap((message) => {
-                    const context = readArtifactContext(message.metadata?.artifactContext);
-                    return context ? [{ messageId: message.id, context }] : [];
-                }),
-                get artifacts() { return conversationArtifacts(); },
-                requestedTurnMode,
-                turnVerbosity,
-                requestApproval,
-                requestRuntimeInput,
-                requestPlanReview,
-                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 ?? {}),
-                            signal: options?.signal ?? abortController.signal,
-                        });
-                    },
-                    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();
-                    },
-                    noReply: async (reason) => {
-                        throwIfAborted();
-                        // First call wins — one silence decision per turn.
-                        if (!deliberatelySilent && reason?.trim()) {
-                            noReplyReason = reason;
-                        }
-                        deliberatelySilent = true;
-                        // `reason` is handler-authored free text: log only that one was given.
-                        console.error(`[canon-sdk] Turn chose no_reply for ${conversationId}`
-                            + ` (reason: ${reason?.trim() ? 'given' : 'none'})`);
-                        // The outcome report deliberately does NOT fire here: `replyFinal`
-                        // still sends after `noReply` (the SDK carve-out — see
-                        // TurnController.noReply in types.ts) and the handler may yet throw
-                        // or be aborted, so only teardown knows whether the silence was
-                        // real. It fires there, once, off the flag set above.
-                    },
-                    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]);
-                        }
-                    },
-                },
-            }));
-            if (submission.status !== 'submitted')
-                return;
-            await disposeInboundHandoffs(handoffs, 'settle', 'handler-completed');
-            // Auto-mark conversation as read after successful processing
-            if (this.options.autoMarkRead) {
-                try {
-                    await this.apiClient.markAsRead(conversationId);
-                }
-                catch {
-                    // Non-critical
-                }
-            }
-        }
-        catch (err) {
-            turnEndedAbnormally = true;
-            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);
-            // Sequenced AFTER the keepalive stops, and with no handoff delay in front
-            // of it: the 3.5 s keepalive would rewrite 'Thinking...' over a blank
-            // scheduled earlier, and every other runtime retires the row and the
-            // typing dots together the moment a turn goes silent. `replyFinal`'s
-            // handoff window overlaps a durable message that has already landed;
-            // here there is nothing to hand off to, and holding the indicator would
-            // read as "started to answer, then gave up".
-            const silentTeardown = deliberatelySilent && !turnEndedAbnormally;
-            // Telemetry parity with the server-answered verb path, decided HERE
-            // because only teardown knows how the turn actually ended: `noReply`
-            // does not gate `replyFinal` in the SDK, and the handler may throw or be
-            // aborted after choosing silence — either would make a report sent at
-            // noReply-call time record silence for a turn that delivered or died.
-            // `durableMessageSequence` counts the turn's durable sends: any durable
-            // message means the turn did not end silent, deliberate flag or not.
-            // reportNoReplyOutcome is fire-and-forget and never throws, so a failed
-            // or rejecting report degrades to exactly the pre-report behavior.
-            if (silentTeardown && durableMessageSequence === 0) {
-                reportNoReplyOutcome(this.apiClient, {
-                    conversationId,
-                    ...(triggeringMessageId ? { messageId: triggeringMessageId } : {}),
-                    ...(noReplyReason ? { reason: noReplyReason } : {}),
-                });
-            }
-            // Always clear typing when done
-            try {
-                await this.typingSignals.clear(conversationId);
-            }
-            catch { }
-            try {
-                // Deliberate silence blanks the node (text '' AND an explicit empty
-                // blocks array) before deleting it, so onStreamingCleared sees empty
-                // content and does not salvage the turn's narration into a durable
-                // bubble. A crashed or interrupted turn keeps the plain clear: there
-                // the salvage is the only record of what the turn managed to say.
-                if (silentTeardown)
-                    await turnOutput.blankAndClear();
-                else
-                    await turnOutput.clear();
-            }
-            catch { }
-            if (runtimeState && !shouldPersistTurnState) {
-                await Promise.resolve(runtimeState.clearTurnState(conversationId)).catch(() => { });
-            }
-        }
-    }
-    // Static registration helpers (unauthenticated)
-    static async register(options) {
-        const { environmentId, baseUrl, streamUrl, rtdbUrl, firebaseApiKey, ...body } = options;
-        const connection = resolveCanonRuntimeConnection({
-            environmentId,
-            apiBaseUrl: baseUrl,
-            streamUrl,
-            rtdbUrl,
-            firebaseWebApiKey: firebaseApiKey,
-        });
-        await verifyCanonRuntimeConnection(connection);
-        return CanonClient.register(connection.apiBaseUrl, body);
-    }
-    static async checkStatus(requestId, options) {
-        const connection = resolveCanonRuntimeConnection({
-            environmentId: options.environmentId,
-            apiBaseUrl: options.baseUrl,
-            streamUrl: options.streamUrl,
-            rtdbUrl: options.rtdbUrl,
-            firebaseWebApiKey: options.firebaseApiKey,
-        });
-        await verifyCanonRuntimeConnection(connection);
-        return CanonClient.checkStatus(connection.apiBaseUrl, requestId, options.pollToken);
-    }
-    static async ackStatus(requestId, options) {
-        const connection = resolveCanonRuntimeConnection({
-            environmentId: options.environmentId,
-            apiBaseUrl: options.baseUrl,
-            streamUrl: options.streamUrl,
-            rtdbUrl: options.rtdbUrl,
-            firebaseWebApiKey: options.firebaseApiKey,
-        });
-        await verifyCanonRuntimeConnection(connection);
-        await CanonClient.ackRegistrationStatus(connection.apiBaseUrl, requestId, options.pollToken);
-    }
-}