@borgee/agents-host 0.2.97 → 0.2.110

package/dist/providers/normalized/adapter.js

@@ -0,0 +1,1650 @@
+import { questionnaireAnswerText, SessionTimeline, SessionObservationProjection, publishSessionTimeline, InputOwnership, NormalizedActivityPublisher, formatTimelineReplacement, createSessionDirectory } from '../../plugin-sdk.js';
+import { recordProtocolTrace, NormalizedObservationGate, sessionControlResponse } from '../../plugin-sdk.js';
+import { createHash, randomUUID } from 'node:crypto';
+import { realpath } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { AgentCommandRejectedError, AgentInputRejectedError, AgentSessionInUseError, PROTOCOL_VERSION, decodeAgentSnapshot, validateNativeInteractionResponse, redactInteractionRequest, redactInteractionResponse } from '../../native-providers.js';
+import { assertHostedInteractionScope, nativeSessionFailureMessage } from './control-policy.js';
+import { InputOwnership as LegacyInputOwnership } from './legacy-input-ownership.js';
+import { parseProviderReply } from '../awaiting-user.js';
+import { buildCodexTurnContext } from '../../context/prompt.js';
+import { buildHostedIncomingContentText } from '../../hosted-turn-content.js';
+import { createHostedProviderCapabilities, ProviderInputRejectedError, ProviderTurnCancelledError } from '../provider-adapter.js';
+import { HostSessionManagement } from './session-management.js';
+const SELECTED_SESSION_NOT_IDLE = 'A native turn is already active in the selected Session.';
+function questionnaireReplyText(item) {
+    return item.text || item.questions.map(question => [question.header, question.prompt, ...question.options.map(option => option.label)].join('\n')).join('\n\n');
+}
+function deferred() {
+    let resolve;
+    let reject;
+    const promise = new Promise((yes, no) => { resolve = yes; reject = no; });
+    void promise.catch(() => { });
+    const value = { fulfilled: false, promise, resolve: (result) => { value.fulfilled = true; resolve(result); }, reject };
+    return value;
+}
+function publicHostInteraction(value) {
+    const request = redactInteractionRequest(value);
+    return request.kind === 'tool_approval'
+        ? { ...request, allowScopes: request.allowScopes.filter(scope => scope === 'once'), policies: undefined }
+        : request.kind === 'permission_approval' ? { ...request, allowScopes: request.allowScopes.filter(scope => scope === 'turn') } : request;
+}
+/** Owns Host binding and business replies; native event interpretation stays in providers. */
+export class NormalizedProviderAdapter {
+    options;
+    outputMode = 'normalized';
+    capabilities = createHostedProviderCapabilities({
+        imageInputTransport: { source: 'transport-derived', support: 'not-supported', reason: 'host-policy-blocked', delivery: [] },
+        progressUpdates: { support: 'supported' },
+    });
+    bindings = new Map();
+    bindingRecords = new Map();
+    relationPasses = new Map();
+    deferredRelations = new Map();
+    busy = new Set();
+    stores = new Map();
+    saving = Promise.resolve();
+    defaultAdmission = Promise.resolve();
+    disposed = false;
+    management;
+    constructor(options) {
+        this.options = options;
+        if (options.sessionManagement && options.provider.descriptor.providerId === 'codex' && 'listSessions' in options.provider && 'inspectSession' in options.provider) {
+            const configuration = options.sessionManagement;
+            this.management = new HostSessionManagement({ ...configuration, provider: options.provider,
+                resolveAgentId: options.resolveAgentId, serverUrl: options.serverUrl,
+                loadProtectedNativeIds: async () => {
+                    const protectedIds = await configuration.loadProtectedNativeIds();
+                    for (const binding of this.bindingRecords.values())
+                        if (!this.hasIndependentOwner(binding))
+                            protectedIds.add(binding.nativeId);
+                    return protectedIds;
+                },
+                find: async (nativeId, channelId, generation) => {
+                    const binding = [...this.bindingRecords.values()].find(row => this.hasIndependentOwner(row) && row.nativeId === nativeId && row.channelId === channelId && this.bindingCurrent(row));
+                    if (!binding)
+                        return undefined;
+                    const info = await binding.session.runtimeInfo();
+                    if (info.sessionId !== nativeId || info.providerId !== 'codex' || !info.cwd || await realpath(info.cwd) !== binding.cwd)
+                        throw new Error('session_native_identity_changed');
+                    const target = this.describeSession({ version: 1, action: 'describe_session', agent_id: binding.agentId, channel_id: channelId, binding_id: binding.bindingId, native_session_id: nativeId, connection_generation: generation }, { signal: new AbortController().signal });
+                    return target ? { target, workspace_path: binding.cwd, persistence: info.persistence } : undefined;
+                },
+                register: (session, channelId, cwd, generation, current) => this.registerIndependentSession(session, channelId, cwd, generation, current), });
+        }
+    }
+    hasIndependentOwner(binding) {
+        for (let owner = binding; owner; owner = owner.source)
+            if (owner.independent)
+                return true;
+        return false;
+    }
+    get supportsDefaultOpening() { return !!this.options.prepareSession; }
+    get supportsSessionManagement() { return !!this.management || this.supportsDefaultOpening; }
+    async describeSessionManagement() {
+        const operations = await this.management?.operations() ?? [];
+        if (this.supportsDefaultOpening && !operations.includes('open_session'))
+            operations.push('open_session');
+        return { operations, ...(operations.includes('open_session') ? { open_targets: [...(this.management ? ['native'] : []), ...(this.supportsDefaultOpening ? ['channel_default'] : [])] } : {}) };
+    }
+    async manageSession(request, context) {
+        if (request.action === 'open_session' && 'target' in request && request.target === 'channel_default')
+            return this.openDefaultSession(request, context);
+        if (this.disposed || !this.management)
+            throw new Error('session_management_not_supported');
+        return request.action === 'discover_sessions' ? this.management.discover(request, context) : this.management.mutate(request, context);
+    }
+    async openDefaultSession(request, context) {
+        const base = { agent_id: request.agent_id, channel_id: request.channel_id, connection_generation: request.connection_generation, operation_id: request.operation_id };
+        if (!this.supportsDefaultOpening)
+            return { ...base, status: 'unsupported', reason: 'session_default_open_unsupported' };
+        const current = () => !this.disposed && request.agent_id === this.options.resolveAgentId() && !context.signal.aborted
+            && !context.connectionSignal?.aborted && context.isConnectionCurrent?.() !== false && Date.now() < request.deadline_at;
+        const assertCurrent = () => { if (!current())
+            throw new Error('stale_session_binding'); };
+        try {
+            return await this.withDefaultAdmission(async () => {
+                assertCurrent();
+                let binding = this.bindings.get(request.channel_id);
+                if (binding && (binding.routingKey !== request.channel_id || !binding.persistent || binding.independent || binding.source))
+                    throw new Error('session_default_identity_changed');
+                if (binding?.observation.status === 'stopped') {
+                    await this.closeBinding(binding);
+                    assertCurrent();
+                    binding = undefined;
+                }
+                if (!binding) {
+                    const records = this.stores.get(request.agent_id) ?? await this.options.store.load(request.agent_id);
+                    assertCurrent();
+                    this.stores.set(request.agent_id, records);
+                    if (!Object.hasOwn(records, request.channel_id))
+                        throw new Error('session_default_not_found');
+                    const promptContext = await this.options.prepareSession(request.channel_id);
+                    assertCurrent();
+                    binding = await this.bindingForDefault({ channelId: request.channel_id, promptContext }, { mode: 'resume-existing', assertCurrent });
+                }
+                assertCurrent();
+                const target = this.describeSession({ version: 1, action: 'describe_session', ...base, binding_id: binding.bindingId, native_session_id: binding.nativeId }, context);
+                if (!target)
+                    throw new Error('stale_session_binding');
+                return { ...base, status: 'confirmed', target, workspace_path: binding.cwd };
+            });
+        }
+        catch (error) {
+            const reason = error instanceof AgentSessionInUseError ? 'session_in_use'
+                : error instanceof Error && ['stale_session_binding', 'session_default_not_found', 'session_default_identity_changed', 'session_default_invalid', 'session_owned_elsewhere'].includes(error.message)
+                    ? error.message : 'session_default_unavailable';
+            return { ...base, status: 'rejected', reason };
+        }
+    }
+    async registerIndependentSession(session, channelId, cwd, generation, current) {
+        const agentId = this.options.resolveAgentId();
+        const info = await session.runtimeInfo();
+        if (!current() || !agentId || !info.sessionId || this.disposed || [...this.bindingRecords.values()].some(row => row.nativeId === info.sessionId && !row.closed))
+            throw new Error('session_owned_elsewhere');
+        const visibilityKey = createHash('sha256').update(JSON.stringify({ independent: true, server: this.options.serverUrl, agentId, channelId, nativeId: info.sessionId })).digest('hex');
+        const now = new Date().toISOString();
+        const timeline = new SessionTimeline({ providerId: info.providerId, nativeSessionId: info.sessionId, visibilityKey }, agentId, channelId);
+        const ownership = new InputOwnership(timeline);
+        const binding = { timeline, projection: new SessionObservationProjection(timeline, ownership, owner => binding.executions.get(owner)?.taskId),
+            bindingId: randomUUID(), routingKey: `independent:${info.sessionId}`, session, nativeId: info.sessionId, channelId, cwd, visibilityKey, agentId,
+            persistent: false, independent: true, retained: true, gate: new NormalizedObservationGate(), ownership, executions: new Map(), ready: deferred(),
+            observation: { status: 'recovering', revision: 1, reason: 'initializing' }, observationQueue: [], observationBytes: 0, pump: Promise.resolve(),
+            requests: new Map(), receipts: new Map(), closed: false, createdAt: now, updatedAt: now, status: info.status };
+        const { persistence: _persistence, ...runtimeInfo } = info;
+        binding.runtime = { type: 'observation', delivery: 'live', sourceKey: `runtime:${randomUUID()}`, occurredAt: Date.now(), event: { type: 'runtime_updated', provider: info.providerId, runtimeInfo } };
+        this.bindingRecords.set(binding.bindingId, binding);
+        binding.pump = this.observe(binding);
+        this.publishBinding(binding, false);
+        const target = this.describeSession({ version: 1, action: 'describe_session', agent_id: agentId, channel_id: channelId, binding_id: binding.bindingId, native_session_id: info.sessionId, connection_generation: generation }, { signal: new AbortController().signal });
+        return { target, workspace_path: cwd };
+    }
+    get sessionInputOperations() { return this.options.provider.descriptor.sessionInputOperations ?? []; }
+    get supportsSessionInput() { return this.sessionInputOperations.length > 0; }
+    sessionPublication;
+    setSessionPublication(publication) { this.sessionPublication = publication; }
+    publishSessionBindings() {
+        if (!this.sessionPublication?.supported())
+            return;
+        for (const binding of this.bindings.values())
+            this.publishBinding(binding, true);
+        for (const binding of this.bindingRecords.values())
+            if (this.bindings.get(binding.channelId) !== binding)
+                this.publishBinding(binding, false);
+    }
+    publishAvailability(binding) {
+        try {
+            return this.publishActivity(binding, { shape: 'normalized_session_availability', sessionControlBindingId: binding.bindingId,
+                nativeSessionId: binding.nativeId, ...binding.observation });
+        }
+        catch {
+            return false;
+        }
+    }
+    setAvailability(binding, status, reason, advance = false) {
+        const safeReason = reason && /^[a-z][a-z0-9_]{0,127}$/.test(reason) ? reason : undefined;
+        if (advance || binding.observation.status !== status || binding.observation.reason !== safeReason) {
+            binding.observation = { status, revision: binding.observation.revision + 1, ...(safeReason ? { reason: safeReason } : {}) };
+        }
+        if (status === 'stopped' && !binding.ready.fulfilled)
+            binding.ready.reject(new Error('Native Session observation is unavailable.'));
+        this.publishAvailability(binding);
+    }
+    visibleRuntime(binding, runtimeInfo) {
+        if (!runtimeInfo.childSessions)
+            return runtimeInfo;
+        return { ...runtimeInfo, childSessions: runtimeInfo.childSessions.filter(child => {
+                if (this.management?.canExpose(child.nativeSessionId, binding.agentId, binding.channelId) === false)
+                    return false;
+                return ![...this.bindingRecords.values()].some(record => !record.closed && record.nativeId === child.nativeSessionId && record.channelId !== binding.channelId);
+            }) };
+    }
+    publishBinding(binding, select) {
+        if (!this.sessionPublication?.supported() || binding.closed || this.disposed || this.bindingRecords.get(binding.bindingId) !== binding || binding.agentId !== this.options.resolveAgentId() || binding.runtime?.event.type !== 'runtime_updated')
+            return false;
+        const availabilityPublished = this.publishAvailability(binding);
+        if (availabilityPublished)
+            binding.retained = true;
+        const runtimeInfo = this.visibleRuntime(binding, structuredClone(binding.runtime.event.runtimeInfo));
+        binding.runtime = { ...binding.runtime, event: { ...binding.runtime.event, runtimeInfo } };
+        if (runtimeInfo.sessionId !== binding.nativeId)
+            return false;
+        const capabilities = structuredClone(this.bindingCapabilities(binding));
+        if (select && this.bindings.get(binding.channelId) !== binding)
+            return false;
+        try {
+            const published = this.sessionPublication.publish(binding.channelId, { shape: 'normalized', protocolVersion: PROTOCOL_VERSION,
+                sessionControlBindingId: binding.bindingId, timelineEpoch: binding.timeline.epoch, ...(select ? { sessionControlDefault: true } : {}), sessionCapabilities: capabilities,
+                event: { type: 'runtime_updated', providerId: this.options.provider.descriptor.providerId, runtimeInfo } });
+            if (published)
+                binding.retained = true;
+            return published;
+        }
+        catch {
+            return false;
+        }
+    }
+    publishActivity(binding, activity) {
+        if (!this.bindingCurrent(binding))
+            return false;
+        if (binding.stateSink?.sessionActivity?.(activity))
+            return true;
+        return this.sessionPublication?.supported() ? this.sessionPublication.publish(binding.channelId, activity) : false;
+    }
+    publisher(binding) {
+        return binding.publisher ??= new NormalizedActivityPublisher({ channelId: binding.channelId, agentId: binding.agentId, get taskId() { return binding.publicationTaskId; },
+            client: { reportActivity: ({ activity }) => { this.publishActivity(binding, activity); } } });
+    }
+    publishPreTurnError(error, options, binding, current, publicMessage) {
+        const agentId = this.options.resolveAgentId();
+        if (!agentId || current && !current())
+            return;
+        const event = {
+            type: 'timeline',
+            provider: this.options.provider.descriptor.providerId,
+            item: { type: 'error', message: publicMessage ?? nativeSessionFailureMessage(error) },
+        };
+        const observation = {
+            type: 'observation',
+            delivery: 'live',
+            sourceKey: `session-error:${randomUUID()}`,
+            occurredAt: Date.now(),
+            event,
+        };
+        try {
+            if (binding && this.bindingCurrent(binding)) {
+                binding.timeline.append(observation);
+                this.publisher(binding).observeTimeline(observation, { scope: binding.timeline.scope, inputs: binding.timeline.inputs, agentId: binding.agentId, channelId: binding.channelId }, binding.bindingId, binding.timeline.epoch);
+            }
+            else
+                options?.onNormalizedObservation?.(event, agentId, observation);
+        }
+        catch {
+            // Error presentation cannot change native admission.
+        }
+    }
+    publishTimeline(binding) {
+        if (!this.bindingCurrent(binding) || !binding.ready.fulfilled || binding.observation.status !== 'available')
+            return false;
+        return publishSessionTimeline({ timeline: binding.timeline, publisher: this.publisher(binding), bindingId: binding.bindingId,
+            agentId: binding.agentId, channelId: binding.channelId, send: activity => this.publishActivity(binding, activity) });
+    }
+    listSessions(request, context) {
+        if (this.disposed || request.agent_id !== this.options.resolveAgentId() || context.signal.aborted || context.isConnectionCurrent?.() === false)
+            throw new Error('stale_session_binding');
+        const entries = [...this.bindingRecords.values()].filter(binding => this.controlBinding(request.channel_id, binding.bindingId) === binding)
+            .map(binding => ({ binding_id: binding.bindingId, native_session_id: binding.nativeId, is_default: this.bindings.get(request.channel_id) === binding }));
+        return createSessionDirectory(request, entries);
+    }
+    describeSession(request, context) {
+        if (request.agent_id !== this.options.resolveAgentId() || context.signal.aborted || context.isConnectionCurrent?.() === false)
+            return undefined;
+        const candidates = request.native_session_id !== undefined && request.binding_id === undefined
+            ? [...this.bindingRecords.values()].filter(record => record.nativeId === request.native_session_id && this.controlBinding(request.channel_id, record.bindingId) === record) : undefined;
+        if (candidates && candidates.length > 1)
+            throw new Error('session_ambiguous');
+        const binding = candidates ? candidates[0] : this.controlBinding(request.channel_id, request.binding_id);
+        if (!binding || request.native_session_id !== undefined && binding.nativeId !== request.native_session_id || request.agent_id !== binding.agentId || context.signal.aborted || context.isConnectionCurrent && !context.isConnectionCurrent())
+            return undefined;
+        const capabilities = this.bindingCapabilities(binding);
+        const input_operations = this.sessionInputOperations.filter(operation => operation === 'start_turn' ? capabilities.sendMessage : operation === 'steer' ? capabilities.steer : capabilities.queueMessage);
+        return { version: 1, agent_id: binding.agentId, channel_id: binding.channelId, binding_id: binding.bindingId, native_session_id: binding.nativeId,
+            connection_generation: request.connection_generation, capabilities, ...(input_operations.length ? { input_operations } : {}) };
+    }
+    async observeSession(request, context) {
+        const input = request.input;
+        const result = (status, reason) => ({ operation_id: input.operation_id, status, ...(reason ? { reason } : {}) });
+        const binding = this.controlBinding(input.channel_id, input.binding_id);
+        const current = () => !!binding && this.bindingCurrent(binding) && !(context.connectionSignal ?? context.signal).aborted && (context.isConnectionCurrent?.() ?? true)
+            && binding.agentId === input.agent_id && binding.bindingId === input.binding_id && binding.nativeId === input.native_session_id;
+        if (!binding || !current())
+            return result('rejected', 'stale_session_binding');
+        if (input.operation !== 'sync_timeline')
+            return result('unsupported');
+        if (binding.observation.status !== 'available') {
+            this.publishAvailability(binding);
+            return result('unconfirmed', `native_observation_${binding.observation.status}`);
+        }
+        const previous = binding.timeline.publication;
+        this.syncNormalizedActivity(input.channel_id, input.binding_id);
+        const published = binding.timeline.publication;
+        return current() && published && published !== previous ? { ...result('confirmed'), timeline_epoch: published.epoch, replacement_id: published.replacementId } : result('unconfirmed');
+    }
+    async generateReply(input, options) {
+        if (this.disposed)
+            throw new Error('The native provider is disposed.');
+        if (input.incomingParts?.some((part) => part.type === 'image')) {
+            throw new ProviderInputRejectedError('Image input requires providerOutputMode: legacy; no native message was submitted.');
+        }
+        const codex = this.options.provider.descriptor.providerId === 'codex';
+        const internalInput = input.collaboration?.turnMode === 'protocol-managed' || input.collaboration?.turnMode === 'silent-kickoff';
+        const unavailableBody = codex && !internalInput && (options?.normalizedInputText === null || options?.normalizedInputMessageId && options.normalizedInputText === undefined);
+        const nativeInput = codex ? (options?.normalizedInputText ?? input.incomingContent) : undefined;
+        const selected = input.selectedSession;
+        const selectedBinding = selected ? this.controlBinding(input.channelId, selected.bindingId) : undefined;
+        const selectedCurrent = () => !!selected && !!selectedBinding && this.bindingCurrent(selectedBinding)
+            && selectedBinding.agentId === selected.agentId && selectedBinding.bindingId === selected.bindingId
+            && selectedBinding.nativeId === selected.nativeSessionId && (selected.sourceCurrent?.() ?? true);
+        if (selected && !selectedCurrent())
+            throw new ProviderInputRejectedError('The selected Session is stale; no native message was submitted.');
+        if (selected) {
+            if (selectedBinding.status !== 'idle' || selectedBinding.inputSubmitting || selectedBinding.controlBusy || selectedBinding.active || selectedBinding.executions.size) {
+                const error = new ProviderInputRejectedError(SELECTED_SESSION_NOT_IDLE);
+                this.publishPreTurnError(error, options, selectedBinding, selectedCurrent, error.publicReplyText);
+                throw error;
+            }
+            selectedBinding.inputSubmitting = true;
+        }
+        else {
+            if (this.busy.has(input.channelId))
+                throw new Error('A native turn is already active in this channel.');
+            this.busy.add(input.channelId);
+        }
+        let binding;
+        let turn;
+        try {
+            if (unavailableBody)
+                throw new ProviderInputRejectedError('The original message body is unavailable; no native message was submitted.');
+            if (codex && !nativeInput?.trim())
+                throw new ProviderInputRejectedError('Add message text before sending attachments to this Session; no native message was submitted.');
+            const prepared = await this.options.prepare(selectedBinding && this.hasIndependentOwner(selectedBinding)
+                ? { ...input, independentSessionWorkspace: { bindingId: selectedBinding.bindingId, cwd: selectedBinding.cwd } } : input);
+            if (codex && prepared.contextPreparationFailed)
+                throw new ProviderInputRejectedError('Required turn context is unavailable; no native message was submitted.');
+            const additionalContext = codex ? buildCodexTurnContext({ ...input, promptContext: prepared.promptContext }) : undefined;
+            if (additionalContext) {
+                let deliveryContext = '';
+                if ((input.incomingMessageType === 'task_assignment' || input.incomingMessageType === 'task_heartbeat') && input.incomingContent !== nativeInput) {
+                    // BPP task delivery prefixes the exact durable body with AgentPreamble and two newlines.
+                    const suffix = `\n\n${nativeInput}`;
+                    if (!input.incomingContent.endsWith(suffix))
+                        throw new ProviderInputRejectedError('The task delivery context boundary is unavailable; no native message was submitted.');
+                    deliveryContext = input.incomingContent.slice(0, -suffix.length);
+                }
+                additionalContext.borgee_delivery = { kind: 'untrusted', value: deliveryContext };
+                additionalContext.borgee_attachments = { kind: 'untrusted', value: buildHostedIncomingContentText(prepared.incomingParts.filter(part => part.type !== 'text')) };
+            }
+            if (prepared.promptContext?.resolvedWorkingFolder?.authority === 'task-thread-scratch') {
+                throw new ProviderInputRejectedError('This task has no authorized execution workspace. Select legacy mode for its discussion-only tool policy; no native message was submitted.');
+            }
+            binding = selectedBinding ?? await this.bindingFor(prepared);
+            await binding.ready.promise;
+            if (binding.observation.status !== 'available')
+                throw new ProviderInputRejectedError('Native Session observation is unavailable; no native message was submitted.');
+            if (selected && !selectedCurrent())
+                throw new ProviderInputRejectedError('The selected Session source expired; no native message was submitted.');
+            if (selected && binding.status !== 'idle')
+                throw new ProviderInputRejectedError('A native turn is already active in the selected Session.');
+            if (binding.closed || binding.controlBusy || binding.active || binding.executions.size)
+                throw new Error('A native turn is already active in this Session.');
+            const questionnaireResponse = selected?.questionnaireResponse;
+            if (questionnaireResponse) {
+                const questionnaire = binding.timeline.questionnaire(questionnaireResponse.messageId);
+                if (!questionnaire || questionnaire.questions.some(question => question.sensitive)) {
+                    throw new ProviderInputRejectedError('The questionnaire is unavailable in the selected Session; no native message was submitted.');
+                }
+                try {
+                    validateNativeInteractionResponse({ kind: 'question', requestId: questionnaire.messageId, questions: questionnaire.questions }, { kind: 'question', answers: questionnaireResponse.answers });
+                }
+                catch {
+                    throw new ProviderInputRejectedError('The questionnaire answers are invalid; no native message was submitted.');
+                }
+                if (options?.normalizedInputText !== questionnaireAnswerText(questionnaire, questionnaireResponse.answers, binding.agentId).trim()) {
+                    throw new ProviderInputRejectedError('The questionnaire answer body does not match its answers; no native message was submitted.');
+                }
+            }
+            turn = { ...(questionnaireResponse ? { questionnaireResponse: structuredClone(questionnaireResponse) } : {}), taskId: options?.normalizedTaskId ?? input.collaboration?.turnExecutionId ?? randomUUID(), result: deferred(), options, started: false, terminal: false, messages: new Map(), ...(selected ? { isCurrent: selectedCurrent } : {}) };
+            if (binding.legacyOwnership)
+                turn.legacyInput = { text: options?.normalizedInputText === undefined ? input.incomingContent : options.normalizedInputText, prompt: prepared.prompt };
+            binding.stateSink?.close();
+            binding.stateSink = options?.normalizedStateSink;
+            binding.active = turn;
+            turn.inputToken = randomUUID();
+            this.registerInput(binding, turn, turn.inputToken, options?.normalizedInputMessageId, turn.inputToken);
+            try {
+                if (binding.runtime)
+                    binding.stateSink?.observe(binding.runtime, binding.agentId, structuredClone(this.bindingCapabilities(binding)), binding.bindingId, binding.timeline.epoch);
+                this.publishTimeline(binding);
+            }
+            catch { /* State synchronization cannot prevent native execution. */ }
+            recordProtocolTrace({ stage: 'provider.input', kind: 'sendMessage',
+                correlation: { channelId: binding.channelId, agentId: binding.agentId, taskId: binding.active?.taskId, sessionId: binding.nativeId },
+                payload: { prompt: codex ? { text: nativeInput, additionalContext } : prepared.prompt } });
+            if (selected && !selectedCurrent())
+                throw new ProviderInputRejectedError('The selected Session source expired; no native message was submitted.');
+            const receipt = await binding.session.sendMessage(nativeInput ?? prepared.prompt, {
+                ...(selected || codex ? { requireIdle: true } : {}), clientMessageId: turn.inputToken,
+                ...(additionalContext ? { additionalContext } : {}),
+            });
+            turn.turnId = receipt?.turnId;
+            await this.applyAssociation(binding, this.confirmInput(binding, turn, turn.inputToken, receipt));
+            if (selected && !selectedCurrent())
+                throw new ProviderInputRejectedError('The selected Session source expired after native admission.');
+            return await turn.result.promise;
+        }
+        catch (error) {
+            const failure = !turn?.started && error instanceof AgentInputRejectedError && error.reason === 'context_unavailable'
+                ? new ProviderInputRejectedError(error.message)
+                : selected && !turn?.started && error instanceof AgentInputRejectedError
+                    ? new ProviderInputRejectedError(SELECTED_SESSION_NOT_IDLE)
+                    : error;
+            if (!turn?.started) {
+                this.publishPreTurnError(failure, options, selected ? selectedBinding : undefined, turn?.isCurrent ?? (selected ? selectedCurrent : undefined), failure instanceof ProviderInputRejectedError ? failure.publicReplyText : undefined);
+            }
+            if (binding && turn?.started && !turn.terminal)
+                this.observeEvent(binding, { type: 'turn_failed', provider: this.options.provider.descriptor.providerId, turnId: turn.turnId, error: error instanceof Error ? error.message : 'Native turn failed.' });
+            if (binding && turn?.inputToken && error instanceof AgentInputRejectedError)
+                binding.ownership.rejectInput(turn.inputToken);
+            turn?.result.reject(failure);
+            throw failure;
+        }
+        finally {
+            if (binding && turn)
+                this.releaseExecution(binding, turn);
+            if (binding && binding.active === turn) {
+                binding.active = undefined;
+            }
+            if (selectedBinding)
+                selectedBinding.inputSubmitting = false;
+            else
+                this.busy.delete(input.channelId);
+            if (binding && !binding.retained && !binding.persistent && !binding.executions.size)
+                await this.closeBinding(binding);
+        }
+    }
+    bindingCurrent(binding) {
+        return !this.disposed && !binding.closed && binding.agentId === this.options.resolveAgentId()
+            && (binding.retained || this.sessionPublication?.supported() ? this.bindingRecords.get(binding.bindingId) === binding : this.bindings.get(binding.channelId) === binding);
+    }
+    controlBinding(channelId, bindingId) {
+        const retained = bindingId ? this.bindingRecords.get(bindingId) : undefined;
+        const binding = bindingId && (retained?.retained || this.sessionPublication?.supported()) ? retained : this.bindings.get(channelId);
+        return binding && binding.channelId === channelId && (!bindingId || binding.bindingId === bindingId) && this.bindingCurrent(binding) ? binding : undefined;
+    }
+    async controlSession(request, context) {
+        const respond = (status, reason) => ({ response: sessionControlResponse(request, status, reason) });
+        const binding = this.controlBinding(request.channel_id, request.binding_id);
+        const isCurrent = () => !!binding && this.bindingCurrent(binding) && (context.isConnectionCurrent?.() ?? !context.connectionSignal?.aborted);
+        const revision = binding?.observation.revision;
+        const current = () => isCurrent() && binding?.observation.status === 'available' && binding.observation.revision === revision && !context.signal.aborted && Date.now() < request.deadline_at;
+        if (!binding || binding.bindingId !== request.binding_id || binding.nativeId !== request.native_session_id || binding.agentId !== request.agent_id)
+            return respond('rejected', 'stale_session_binding');
+        if (!isCurrent() || context.signal.aborted || Date.now() >= request.deadline_at)
+            return respond('unconfirmed', 'session_control_expired');
+        if (binding.observation.status !== 'available')
+            return respond('rejected', `native_observation_${binding.observation.status}`);
+        if (request.operation.kind === 'send_input')
+            return this.sendInput(binding, request, context);
+        if (request.operation.kind === 'list_pending_inputs') {
+            if (!this.supportsSessionInput || !this.bindingCapabilities(binding).queueMessage || !binding.session.listPendingInputs)
+                return respond('unsupported', 'native_queue_inventory_not_supported');
+            try {
+                const pending = await binding.session.listPendingInputs();
+                if (!current() || context.isConnectionCurrent && !context.isConnectionCurrent())
+                    return respond('unconfirmed', 'session_control_expired');
+                return { response: { ...sessionControlResponse(request, 'confirmed'), result: { pending_native_message_ids: pending } } };
+            }
+            catch {
+                return respond('unconfirmed', 'native_queue_inventory_unavailable');
+            }
+        }
+        if (request.operation.kind === 'list_commands') {
+            if (!this.bindingCapabilities(binding).commands || !binding.session.listCommands)
+                return respond('unsupported', 'commands_not_supported');
+            try {
+                const commands = await binding.session.listCommands();
+                if (!current())
+                    return respond('unconfirmed', 'session_control_expired');
+                return { response: { ...sessionControlResponse(request, 'confirmed'), result: { commands } } };
+            }
+            catch {
+                return respond('unconfirmed', 'command_directory_unavailable');
+            }
+        }
+        if (binding.controlBusy || this.bindings.get(binding.channelId) === binding && this.busy.has(binding.channelId) || binding.active || binding.executions.size || binding.requests.size)
+            return respond('rejected', 'session_busy');
+        binding.controlBusy = true;
+        let turn;
+        let invoked = false;
+        let completion;
+        const release = () => {
+            if (turn)
+                this.releaseExecution(binding, turn);
+            if (turn && binding.active === turn)
+                binding.active = undefined;
+            binding.controlBusy = false;
+        };
+        try {
+            const info = await binding.session.runtimeInfo();
+            if (!current())
+                return respond('unconfirmed', 'session_control_expired');
+            if (info.status !== 'idle')
+                return respond('rejected', 'session_busy');
+            const operation = request.operation;
+            if (operation.kind === 'set_setting') {
+                if (!this.bindingCapabilities(binding).sessionSettings || !binding.session.setSessionSetting)
+                    return respond('unsupported', 'settings_not_supported');
+                const setting = info.settings?.find(value => value.id === operation.setting_id);
+                if (!setting?.mutable || setting.category === 'permissions' || !setting.options.some(option => option.value === operation.value))
+                    return respond('rejected', 'setting_not_allowed');
+                invoked = true;
+                await binding.session.setSessionSetting(operation.setting_id, operation.value);
+            }
+            else if (operation.kind === 'set_planning') {
+                if (!this.bindingCapabilities(binding).planning || !binding.session.setPlanning)
+                    return respond('unsupported', 'planning_not_supported');
+                invoked = true;
+                await binding.session.setPlanning(operation.active);
+            }
+            else {
+                if (!this.bindingCapabilities(binding).commands || !binding.session.executeCommand || !request.admission || !context.execution && !context.activateExecution)
+                    return respond('unsupported', 'command_execution_not_supported');
+                const execution = context.execution ?? await context.activateExecution(isCurrent);
+                turn = { taskId: request.admission.input_message_id, result: deferred(), options: execution, started: false, terminal: false, messages: new Map(), commandSettled: false, isCurrent };
+                if (binding.legacyOwnership)
+                    turn.legacyInput = { text: execution.normalizedInputText ?? null, prompt: '' };
+                binding.stateSink?.close();
+                binding.stateSink = execution.normalizedStateSink;
+                binding.active = turn;
+                turn.inputToken = randomUUID();
+                this.registerInput(binding, turn, turn.inputToken, request.admission.input_message_id);
+                // Legacy native commands claim their first observed turn before the command receipt.
+                binding.legacyOwnership?.settle(turn, undefined);
+                completion = turn.result.promise.then(reply => reply.text ? reply : undefined).finally(release);
+                void completion.catch(() => { });
+                context.onCompletion?.(completion);
+                invoked = true;
+                const result = await binding.session.executeCommand(operation.command_id, operation.args);
+                turn.commandSettled = true;
+                turn.expectsNativeTurn = result.execution === 'turn';
+                turn.commandTurnId = result.turnId;
+                if (result.turnId && turn.turnId && turn.turnId !== result.turnId) {
+                    const error = new Error('The native command returned a different turn from the observed command execution.');
+                    turn.terminal = true;
+                    turn.result.reject(error);
+                    throw error;
+                }
+                if (result.turnId && !turn.turnId)
+                    turn.turnId = result.turnId;
+                const receipt = result.messageId ? { messageId: result.messageId, turnId: result.turnId } : result.turnId ? { turnId: result.turnId } : undefined;
+                await this.applyAssociation(binding, this.confirmInput(binding, turn, turn.inputToken, receipt));
+                await this.finishLocalCommand(binding, turn);
+                const response = sessionControlResponse(request, current() ? 'confirmed' : 'unconfirmed', current() ? undefined : 'session_control_expired');
+                if (response.status === 'confirmed' && result.text !== undefined)
+                    response.result = { text: result.text };
+                return { response, completion };
+            }
+            const confirmed = await binding.session.runtimeInfo();
+            if (!current())
+                return respond('unconfirmed', 'session_control_expired');
+            if (operation.kind === 'set_setting' ? confirmed.settings?.find(setting => setting.id === operation.setting_id)?.value !== operation.value : confirmed.planning?.active !== operation.active)
+                return respond('unconfirmed', 'native_confirmation_missing');
+            await this.persistConfirmedBinding(binding, confirmed, current);
+            if (!current())
+                return respond('unconfirmed', 'session_control_expired');
+            this.syncNormalizedActivity(binding.channelId, binding.bindingId);
+            return respond('confirmed');
+        }
+        catch (error) {
+            if (error instanceof AgentCommandRejectedError && turn && !turn.started && !binding.requests.size) {
+                turn.terminal = true;
+                turn.result.resolve({ text: '' });
+                return { ...respond('rejected', 'native_command_rejected'), completion };
+            }
+            return { ...respond(invoked ? 'unconfirmed' : 'rejected', invoked ? 'native_confirmation_unavailable' : 'session_control_unavailable'), ...(completion ? { completion } : {}) };
+        }
+        finally {
+            if (!completion)
+                release();
+        }
+    }
+    registerInput(binding, turn, key, clientMessageId, issuedToken, expectedTurnId) {
+        turn.ownerId ??= randomUUID();
+        if (binding.legacyOwnership) {
+            binding.legacyOwnership.register(turn, turn.legacyInput && { ...turn.legacyInput, clientMessageId });
+            binding.executions.set(turn.ownerId, turn);
+            return;
+        }
+        const result = binding.ownership.register({ key, owner: turn.ownerId, clientMessageId, taskId: turn.taskId, issuedToken, expectedTurnId, questionnaireResponse: turn.questionnaireResponse });
+        if (result.status !== 'changed' && result.status !== 'unchanged')
+            throw new Error(`Native input admission ${result.status}.`);
+        binding.executions.set(turn.ownerId, turn);
+    }
+    confirmInput(binding, turn, key, receipt) {
+        if (!binding.legacyOwnership)
+            return binding.ownership.confirm(key, receipt);
+        return { status: 'unchanged', correlations: [], unavailableOwners: [], owned: binding.legacyOwnership.settle(turn, receipt).map(value => ({ owner: value.owner.ownerId, observation: value.observation })) };
+    }
+    releaseExecution(binding, turn) {
+        binding.legacyOwnership?.remove(turn);
+        if (turn.ownerId) {
+            binding.ownership.releaseOwner(turn.ownerId);
+            binding.executions.delete(turn.ownerId);
+        }
+    }
+    reconcileAssociationMetadata(binding, result) {
+        for (const owner of result.unavailableOwners)
+            binding.executions.get(owner)?.result.reject(new Error('Native input execution evidence unavailable.'));
+        return result.correlations.some(value => value.status === 'changed');
+    }
+    async applyAssociation(binding, result) {
+        const revision = binding.observation.revision;
+        let changed = this.reconcileAssociationMetadata(binding, result);
+        for (const owned of result.owned) {
+            const turn = binding.executions.get(owned.owner);
+            if (!turn)
+                continue;
+            changed = binding.projection.attributeOwned(owned).changed || changed;
+            await this.observeOwned(binding, turn, owned.observation);
+            if (binding.observation.revision !== revision || !this.bindingCurrent(binding))
+                return;
+        }
+        if (changed)
+            this.publishTimeline(binding);
+    }
+    observeOwned(binding, turn, observation) {
+        const revision = binding.observation.revision;
+        const work = (binding.ownedObservationWork ?? Promise.resolve()).then(() => this.processOwnedObservation(binding, turn, observation, revision));
+        binding.ownedObservationWork = work;
+        return work;
+    }
+    async processOwnedObservation(binding, turn, observation, revision) {
+        if (binding.observation.revision !== revision || !this.bindingCurrent(binding))
+            return;
+        if (turn.terminal)
+            return;
+        if (turn.isCurrent && !turn.isCurrent()) {
+            turn.result.reject(new ProviderTurnCancelledError('Native input connection ownership ended.'));
+            return;
+        }
+        if (binding.active !== turn) {
+            if (binding.active && !binding.active.terminal)
+                throw new Error('Native input observations overlap distinct owned turns.');
+            binding.active = turn;
+        }
+        if (observation.event.type === 'turn_started' && turn.activate) {
+            try {
+                turn.options = await turn.activate();
+            }
+            catch (error) {
+                turn.terminal = true;
+                turn.result.reject(error);
+                if (binding.active === turn)
+                    binding.active = undefined;
+                return;
+            }
+            turn.activate = undefined;
+            if (binding.observation.revision !== revision || !this.bindingCurrent(binding)) {
+                turn.options.normalizedStateSink?.close();
+                return;
+            }
+            if (turn.isCurrent && !turn.isCurrent()) {
+                turn.options.normalizedStateSink?.close();
+                const error = new ProviderTurnCancelledError('Native input connection ownership ended during execution admission.');
+                turn.terminal = true;
+                turn.result.reject(error);
+                if (binding.active === turn)
+                    binding.active = undefined;
+                return;
+            }
+            binding.stateSink?.close();
+            binding.stateSink = turn.options.normalizedStateSink;
+        }
+        if (binding.legacyOwnership && observation.event.type === 'timeline' && observation.event.item.type === 'user_message') {
+            observation = binding.legacyOwnership.publicObservation(observation, turn);
+            binding.timeline.append(observation);
+            const event = observation.event;
+            if (event.type === 'timeline' && event.item.type === 'user_message' && event.item.messageId && event.item.clientMessageId) {
+                binding.timeline.inputs.accept(binding.timeline.scope, event.item.messageId, { clientMessageId: event.item.clientMessageId, taskId: turn.taskId });
+            }
+            if (turn.legacyInput?.text === null)
+                return;
+            this.observeSessionState(binding, observation, turn.taskId);
+        }
+        this.observeEvent(binding, observation.event, observation);
+    }
+    async sendInput(binding, request, context) {
+        const operation = request.operation;
+        const respond = (status, reason) => ({ response: sessionControlResponse(request, status, reason) });
+        if (operation.kind !== 'send_input' || !request.admission || !this.supportsSessionInput)
+            return respond('unsupported', 'native_input_not_supported');
+        if (!this.sessionInputOperations.includes(operation.delivery))
+            return respond('unsupported', 'native_input_delivery_not_supported');
+        if (binding.inputSubmitting)
+            return respond('rejected', 'native_input_submission_busy');
+        const isCurrent = () => this.bindingCurrent(binding) && (context.isConnectionCurrent?.() ?? !context.signal.aborted);
+        const revision = binding?.observation.revision;
+        const current = () => isCurrent() && binding?.observation.status === 'available' && binding.observation.revision === revision && !context.signal.aborted && Date.now() < request.deadline_at;
+        if (!current())
+            return respond('unconfirmed', 'session_control_expired');
+        const active = binding.active;
+        if (operation.delivery === 'steer' && (!this.bindingCapabilities(binding).steer || !binding.session.steer))
+            return respond('unsupported', 'native_steering_not_supported');
+        if (operation.delivery === 'steer' && (!active?.started || active.terminal || active.turnId !== operation.expected_turn_id))
+            return respond('rejected', 'native_turn_changed');
+        if (operation.delivery === 'next_turn' && (!this.bindingCapabilities(binding).queueMessage || !context.activateExecution))
+            return respond('unsupported', 'native_queue_not_supported');
+        binding.inputSubmitting = true;
+        let queued;
+        let completion;
+        let invoked = false;
+        const inputKey = randomUUID();
+        try {
+            if (operation.delivery === 'next_turn') {
+                queued = { taskId: request.admission.input_message_id, started: false, terminal: false, messages: new Map(), result: deferred(), isCurrent, activate: () => context.activateExecution(isCurrent) };
+                if (binding.legacyOwnership)
+                    queued.legacyInput = { text: operation.text, prompt: operation.text };
+                queued.inputToken = inputKey;
+                this.registerInput(binding, queued, inputKey, request.admission.input_message_id, inputKey);
+                const owned = queued;
+                const disconnected = () => owned.result.reject(new ProviderTurnCancelledError('Native input connection ownership ended.'));
+                context.connectionSignal?.addEventListener('abort', disconnected, { once: true });
+                completion = owned.result.promise.then(reply => reply.text ? reply : undefined).finally(() => {
+                    context.connectionSignal?.removeEventListener('abort', disconnected);
+                    this.releaseExecution(binding, owned);
+                    if (binding.active === owned)
+                        binding.active = undefined;
+                });
+                void completion.catch(() => { });
+                context.onCompletion?.(completion);
+                if (context.connectionSignal?.aborted || !isCurrent()) {
+                    disconnected();
+                    return { ...respond('unconfirmed', 'session_control_expired'), completion };
+                }
+            }
+            else {
+                this.registerInput(binding, active, inputKey, request.admission.input_message_id, inputKey, operation.expected_turn_id);
+            }
+            invoked = true;
+            const receipt = operation.delivery === 'next_turn'
+                ? await binding.session.sendMessage(operation.text, { delivery: 'next_turn', clientMessageId: inputKey })
+                : await binding.session.steer(operation.text, { expectedTurnId: operation.expected_turn_id, clientMessageId: inputKey });
+            if (!receipt || !receipt.messageId && !receipt.turnId)
+                return { ...respond('unconfirmed', 'native_input_identity_missing'), completion };
+            if (queued) {
+                queued.turnId = receipt.turnId;
+            }
+            const association = this.confirmInput(binding, queued ?? active, inputKey, receipt);
+            await this.applyAssociation(binding, association);
+            const turnId = binding.ownership.turnId((queued ?? active).ownerId);
+            if (association.status === 'conflict' || operation.delivery === 'steer' && turnId !== operation.expected_turn_id)
+                return { ...respond('unconfirmed', 'native_turn_changed'), completion };
+            if (!current())
+                return { ...respond('unconfirmed', 'session_control_expired'), completion };
+            return { response: { ...sessionControlResponse(request, 'confirmed'), result: { input_receipt: { delivery: operation.delivery, ...(receipt.messageId ? { native_message_id: receipt.messageId } : {}), ...(turnId ? { turn_id: turnId } : {}) } } }, completion };
+        }
+        catch (error) {
+            if (error instanceof AgentInputRejectedError || !invoked)
+                binding.ownership.rejectInput(inputKey);
+            if (error instanceof AgentInputRejectedError && queued) {
+                queued.terminal = true;
+                queued.result.resolve({ text: '' });
+            }
+            return { ...respond(error instanceof AgentInputRejectedError || !invoked ? 'rejected' : 'unconfirmed', error instanceof AgentInputRejectedError ? 'native_input_rejected' : error instanceof Error && error.message === 'Native input admission capacity.' ? 'native_input_capacity' : 'native_confirmation_unavailable'), completion };
+        }
+        finally {
+            binding.inputSubmitting = false;
+        }
+    }
+    async finishLocalCommand(binding, turn) {
+        const current = () => this.bindingCurrent(binding) && (turn.isCurrent?.() ?? true) && binding.active === turn && !turn.terminal;
+        if (!current() || !turn.commandSettled || turn.commandFinishing || turn.started || turn.expectsNativeTurn || binding.requests.size)
+            return;
+        turn.commandFinishing = true;
+        try {
+            const info = await binding.session.runtimeInfo();
+            if (!current() || turn.started || binding.requests.size || info.status !== 'idle')
+                return;
+            await this.persistConfirmedBinding(binding, info, current);
+            if (!current() || turn.started || binding.requests.size)
+                return;
+            turn.terminal = true;
+            turn.result.resolve({ text: '' });
+            this.syncNormalizedActivity(binding.channelId, binding.bindingId);
+        }
+        catch {
+            // An unconfirmed local command retains ownership until native state is known.
+        }
+        finally {
+            turn.commandFinishing = false;
+        }
+    }
+    async persistConfirmedBinding(binding, info, current, selecting = false) {
+        if (!binding.persistent)
+            return;
+        if (!info.persistence || info.persistence.sessionId !== binding.nativeId || info.persistence.providerId !== this.options.provider.descriptor.providerId)
+            throw new Error('Native session persistence identity changed.');
+        const record = JSON.stringify({ handle: info.persistence, cwd: binding.cwd, visibilityKey: binding.visibilityKey, additionalDirectories: binding.additionalDirectories });
+        this.saving = this.saving.catch(() => { }).then(async () => {
+            if (!current())
+                throw new Error('Native session confirmation expired before persistence.');
+            if (!selecting && this.bindings.get(binding.channelId) !== binding)
+                return;
+            const records = this.stores.get(binding.agentId);
+            const next = { ...records, [binding.routingKey]: record };
+            await this.options.store.save(binding.agentId, next);
+            if (current())
+                records[binding.routingKey] = record;
+        });
+        await this.saving;
+    }
+    withDefaultAdmission(work) {
+        if (this.management)
+            return this.management.withAdmission(work);
+        if (!this.supportsDefaultOpening)
+            return work();
+        const result = this.defaultAdmission.catch(() => { }).then(work);
+        this.defaultAdmission = result;
+        return result;
+    }
+    bindingFor(turn) {
+        return this.withDefaultAdmission(() => this.bindingForDefault(turn));
+    }
+    async bindingForDefault(turn, admission) {
+        const agentId = this.options.resolveAgentId();
+        const resumeOnly = admission?.mode === 'resume-existing';
+        if (!agentId)
+            throw new Error('A verified Borgee agent identity is required for native sessions.');
+        const assertCurrent = () => {
+            if (this.disposed || agentId !== this.options.resolveAgentId())
+                throw new Error('stale_session_binding');
+            admission?.assertCurrent();
+        };
+        assertCurrent();
+        const cwd = await realpath(turn.promptContext?.resolvedWorkingFolder?.rootPath ?? process.cwd());
+        assertCurrent();
+        const additionalDirectories = this.options.provider.descriptor.providerId === 'claude'
+            ? resolveAdditionalDirectories(turn) : undefined;
+        const routingKey = turn.providerSessionRouting?.key ?? turn.channelId;
+        const persistent = turn.providerSessionRouting?.persistence !== 'ephemeral';
+        const visibilityKey = createHash('sha256').update(JSON.stringify({
+            agentId, server: this.options.serverUrl, channelId: turn.channelId, routingKey,
+            context: turn.promptContext?.channelContextPayloadPath ?? null,
+            credentials: turn.promptContext?.gatewayCredentialPath ?? null,
+            brief: turn.promptContext?.claudeProjectedBriefPath ?? null,
+        })).digest('hex');
+        const existing = [...this.bindingRecords.values()].find(binding => !binding.source && !binding.closed && binding.agentId === agentId
+            && binding.channelId === turn.channelId && binding.cwd === cwd && binding.visibilityKey === visibilityKey && binding.persistent === persistent
+            && JSON.stringify(binding.additionalDirectories) === JSON.stringify(additionalDirectories));
+        if (existing) {
+            const previous = this.bindings.get(turn.channelId);
+            if (previous !== existing && existing.persistent) {
+                await this.persistConfirmedBinding(existing, await existing.session.runtimeInfo(), () => !this.disposed && !existing.closed
+                    && this.bindings.get(turn.channelId) === previous && this.bindingRecords.get(existing.bindingId) === existing, true);
+            }
+            assertCurrent();
+            await this.selectBinding(existing);
+            assertCurrent();
+            return existing;
+        }
+        const records = this.stores.get(agentId) ?? await this.options.store.load(agentId);
+        assertCurrent();
+        this.stores.set(agentId, records);
+        let stored;
+        if (persistent && records[routingKey]) {
+            try {
+                stored = JSON.parse(records[routingKey]);
+            }
+            catch {
+                throw new Error(resumeOnly ? 'session_default_invalid' : 'Invalid native session binding.');
+            }
+        }
+        if (resumeOnly) {
+            if (!stored)
+                throw new Error('session_default_invalid');
+            if (!stored.handle || stored.handle.providerId !== this.options.provider.descriptor.providerId || typeof stored.handle.sessionId !== 'string'
+                || !stored.handle.sessionId || typeof stored.handle.opaque !== 'string' || typeof stored.cwd !== 'string' || typeof stored.visibilityKey !== 'string')
+                throw new Error('session_default_invalid');
+            if (stored.cwd !== cwd || stored.visibilityKey !== visibilityKey)
+                throw new Error('session_default_identity_changed');
+        }
+        const handle = stored?.cwd === cwd && stored.visibilityKey === visibilityKey ? stored.handle : undefined;
+        if (handle) {
+            await this.management?.assertUnclaimed(handle.sessionId);
+            assertCurrent();
+            const loaded = [...this.bindingRecords.values()].filter(binding => binding.nativeId === handle.sessionId);
+            if (loaded.some(binding => !binding.closed))
+                throw new Error('Native session is already loaded with different Host configuration.');
+            for (const binding of loaded) {
+                await this.closeBinding(binding);
+                assertCurrent();
+            }
+        }
+        assertCurrent();
+        const session = handle
+            ? await this.options.provider.resumeSession(handle, ...(additionalDirectories === undefined ? [] : [{ additionalDirectories }]))
+            : await this.options.provider.createSession({ sessionId: routingKey, cwd, systemPrompt: turn.claudeSessionPromptAppend,
+                ...(additionalDirectories === undefined ? {} : { additionalDirectories }) });
+        if ([...this.bindingRecords.values()].some(binding => binding.session === session))
+            throw new Error('Native session is already owned by another Host binding.');
+        let createdBinding;
+        try {
+            assertCurrent();
+            await this.options.configureSession(session);
+            assertCurrent();
+            const info = await session.runtimeInfo();
+            assertCurrent();
+            if (resumeOnly && info.providerId !== this.options.provider.descriptor.providerId)
+                throw new Error('session_default_identity_changed');
+            if (!info.sessionId)
+                throw new Error('Native provider did not return a session identity.');
+            await this.management?.assertUnclaimed(info.sessionId);
+            assertCurrent();
+            if (this.management && [...this.bindingRecords.values()].some(binding => binding.nativeId === info.sessionId && !binding.closed))
+                throw new Error('Native session is already owned by another Host binding.');
+            if (handle && info.sessionId !== handle.sessionId)
+                throw new Error(resumeOnly ? 'session_default_identity_changed' : 'Resumed native identity differs from the stored Host binding.');
+            if (info.cwd && await realpath(info.cwd) !== cwd)
+                throw new Error(resumeOnly ? 'session_default_identity_changed' : 'Native session working directory differs from the authorized Host binding.');
+            assertCurrent();
+            if (persistent) {
+                if (!info.persistence || info.persistence.sessionId !== info.sessionId || info.persistence.providerId !== this.options.provider.descriptor.providerId)
+                    throw new Error(resumeOnly ? 'session_default_identity_changed' : 'Native provider did not return a matching persistence handle.');
+                if (!resumeOnly) {
+                    records[routingKey] = JSON.stringify({ handle: info.persistence, cwd, visibilityKey, additionalDirectories });
+                    this.saving = this.saving.catch(() => { }).then(() => this.options.store.save(agentId, { ...records }));
+                    await this.saving;
+                    assertCurrent();
+                }
+            }
+            const now = new Date().toISOString();
+            const timeline = new SessionTimeline({ providerId: this.options.provider.descriptor.providerId, nativeSessionId: info.sessionId, visibilityKey }, agentId, turn.channelId);
+            const ownership = new InputOwnership(timeline);
+            const binding = { timeline, projection: new SessionObservationProjection(timeline, ownership, owner => binding.executions.get(owner)?.taskId), bindingId: randomUUID(), routingKey, session, nativeId: info.sessionId, channelId: turn.channelId, cwd, visibilityKey, additionalDirectories, agentId, persistent, retained: false, gate: new NormalizedObservationGate(), ownership, executions: new Map(), ready: deferred(), observation: { status: 'recovering', revision: 1, reason: 'initializing' }, observationQueue: [], observationBytes: 0, pump: Promise.resolve(), requests: new Map(), receipts: new Map(), closed: false, createdAt: now, updatedAt: now, status: info.status };
+            const { persistence: _persistence, ...runtimeInfo } = info;
+            binding.runtime = { type: 'observation', delivery: 'live', sourceKey: `runtime:${randomUUID()}`, occurredAt: Date.now(), event: { type: 'runtime_updated', provider: this.options.provider.descriptor.providerId, runtimeInfo } };
+            assertCurrent();
+            createdBinding = binding;
+            this.bindingRecords.set(binding.bindingId, binding);
+            if (this.options.provider.descriptor.providerId !== 'codex')
+                binding.legacyOwnership = new LegacyInputOwnership(true);
+            binding.pump = this.observe(binding);
+            await this.selectBinding(binding);
+            assertCurrent();
+            return binding;
+        }
+        catch (error) {
+            if (createdBinding)
+                await this.closeBinding(createdBinding);
+            else
+                await session.dispose();
+            throw error;
+        }
+    }
+    admitChildren(source, relationsChanged = false) {
+        if (!this.sessionPublication?.supported() || !this.options.provider.openChildSession || !this.bindingCurrent(source))
+            return;
+        const running = this.relationPasses.get(source.channelId);
+        if (running) {
+            if (!running.inspected.has(source.nativeId) && !running.queue.some(binding => binding.nativeId === source.nativeId))
+                running.queue.push(source);
+            else if (relationsChanged)
+                void running.promise.then(() => this.admitChildren(source));
+            return;
+        }
+        const queue = [...(this.deferredRelations.get(source.channelId) ?? []), source];
+        const inspected = new Set();
+        const expanded = new Set();
+        const retry = [];
+        const pass = Promise.resolve().then(async () => {
+            while (queue.length) {
+                const binding = queue.shift();
+                if (!this.bindingCurrent(binding) || expanded.has(binding.nativeId))
+                    continue;
+                if (!inspected.has(binding.nativeId)) {
+                    if (inspected.size >= 64) {
+                        queue.unshift(binding);
+                        break;
+                    }
+                    inspected.add(binding.nativeId);
+                    try {
+                        const info = await binding.session.runtimeInfo();
+                        if (!this.bindingCurrent(binding) || info.sessionId !== binding.nativeId || info.providerId !== this.options.provider.descriptor.providerId)
+                            continue;
+                        const previous = binding.runtime?.event.type === 'runtime_updated' ? binding.runtime.event.runtimeInfo.childSessions ?? [] : [];
+                        const children = new Map(previous.map(child => [child.nativeSessionId, child]));
+                        for (const child of info.childSessions ?? [])
+                            children.set(child.nativeSessionId, child);
+                        const { persistence: _persistence, ...runtimeInfo } = info;
+                        binding.runtime = { type: 'observation', delivery: 'live', sourceKey: `runtime:${randomUUID()}`, occurredAt: Date.now(), event: { type: 'runtime_updated', provider: info.providerId, runtimeInfo: { ...runtimeInfo, childSessions: [...children.values()] } } };
+                        this.publishBinding(binding, false);
+                    }
+                    catch {
+                        continue;
+                    }
+                }
+                expanded.add(binding.nativeId);
+                await this.adoptKnownChildren(binding, inspected, queue, retry);
+            }
+        }).finally(() => {
+            this.deferredRelations.set(source.channelId, [...new Set([...queue, ...retry])]);
+            this.relationPasses.delete(source.channelId);
+            source.admitting = undefined;
+        });
+        this.relationPasses.set(source.channelId, { promise: pass, queue, inspected });
+        source.admitting = pass;
+    }
+    async adoptKnownChildren(source, inspected, queue, retry) {
+        const descriptors = source.runtime?.event.type === 'runtime_updated' ? source.runtime.event.runtimeInfo.childSessions ?? [] : [];
+        for (const descriptor of descriptors) {
+            if (!this.bindingCurrent(source))
+                return;
+            const known = [...this.bindingRecords.values()].find(record => record.channelId === source.channelId && record.nativeId === descriptor.nativeSessionId && this.bindingCurrent(record));
+            if (known) {
+                queue.push(known);
+                continue;
+            }
+            if (inspected.has(descriptor.nativeSessionId))
+                continue;
+            if (inspected.size >= 64) {
+                retry.push(source);
+                continue;
+            }
+            inspected.add(descriptor.nativeSessionId);
+            const admit = async () => {
+                let session;
+                try {
+                    session = await this.options.provider.openChildSession(source.nativeId, descriptor.nativeSessionId);
+                    if (!this.bindingCurrent(source))
+                        return;
+                    const info = await session.runtimeInfo();
+                    if (!this.bindingCurrent(source) || info.sessionId !== descriptor.nativeSessionId || info.providerId !== this.options.provider.descriptor.providerId)
+                        return;
+                    if (info.cwd && await realpath(info.cwd) !== source.cwd)
+                        return;
+                    if ([...this.bindingRecords.values()].some(record => record.session === session || !record.closed && record.nativeId === info.sessionId))
+                        return;
+                    const now = new Date().toISOString();
+                    const timeline = new SessionTimeline({ providerId: info.providerId, nativeSessionId: info.sessionId, visibilityKey: source.visibilityKey }, source.agentId, source.channelId);
+                    const ownership = new InputOwnership(timeline);
+                    const binding = { bindingId: randomUUID(), routingKey: source.routingKey, session, nativeId: info.sessionId, channelId: source.channelId,
+                        cwd: source.cwd, visibilityKey: source.visibilityKey, additionalDirectories: source.additionalDirectories, agentId: source.agentId, persistent: false, retained: false, source,
+                        timeline, projection: new SessionObservationProjection(timeline, ownership, owner => binding.executions.get(owner)?.taskId),
+                        gate: new NormalizedObservationGate(), ownership, executions: new Map(), ready: deferred(), observation: { status: 'recovering', revision: 1, reason: 'initializing' }, observationQueue: [], observationBytes: 0, pump: Promise.resolve(), requests: new Map(), receipts: new Map(),
+                        closed: false, createdAt: now, updatedAt: now, status: info.status };
+                    const { persistence: _persistence, ...runtimeInfo } = info;
+                    binding.runtime = { type: 'observation', delivery: 'live', sourceKey: `runtime:${randomUUID()}`, occurredAt: Date.now(), event: { type: 'runtime_updated', provider: info.providerId, runtimeInfo } };
+                    this.bindingRecords.set(binding.bindingId, binding);
+                    queue.push(binding);
+                    session = undefined;
+                    if (this.options.provider.descriptor.providerId !== 'codex')
+                        binding.legacyOwnership = new LegacyInputOwnership(true);
+                    binding.pump = this.observe(binding);
+                    this.publishBinding(binding, false);
+                }
+                catch {
+                    // A source may advertise a child before its native handle is available.
+                }
+                finally {
+                    if (session && ![...this.bindingRecords.values()].some(record => record.session === session))
+                        await session.dispose();
+                }
+            };
+            if (this.management)
+                await this.management.admitUnclaimed(descriptor.nativeSessionId, admit).catch(() => { });
+            else
+                await admit();
+        }
+    }
+    observeSessionState(binding, observation, taskId) {
+        if (!this.bindingCurrent(binding))
+            return;
+        let event = observation.event;
+        if (event.type === 'runtime_updated')
+            return;
+        binding.publicationTaskId = taskId;
+        if (event.type === 'interaction_requested') {
+            binding.requestTasks ??= new Map();
+            binding.requestTasks.set(event.request.requestId, taskId);
+            binding.requests.set(event.request.requestId, event.request);
+            event = { ...event, request: publicHostInteraction(event.request) };
+        }
+        else if (event.type === 'interaction_resolved') {
+            const request = binding.requests.get(event.requestId);
+            if (!request || request.kind !== event.response.kind)
+                return;
+            const response = redactInteractionResponse(request, event.response);
+            binding.publicationTaskId = binding.requestTasks?.get(event.requestId);
+            binding.requestTasks?.delete(event.requestId);
+            binding.requests.delete(event.requestId);
+            binding.receipts.get(event.requestId)?.resolve(response);
+            event = { ...event, response };
+        }
+        if (!this.sessionPublication?.supported() && !binding.publisher?.hasTimelineSource(observation))
+            return;
+        if (event.type === 'timeline')
+            this.publisher(binding).observeTimeline({ ...observation, event }, { scope: binding.timeline.scope, inputs: binding.timeline.inputs, agentId: binding.agentId, channelId: binding.channelId }, binding.bindingId, binding.timeline.epoch);
+        else
+            this.publisher(binding).observe({ ...observation, event }, undefined, binding.bindingId, binding.timeline.epoch);
+    }
+    async selectBinding(binding) {
+        const previous = this.bindings.get(binding.channelId);
+        if (previous === binding)
+            return;
+        this.bindings.set(binding.channelId, binding);
+        this.publishBinding(binding, true);
+        if (previous) {
+            if (!this.sessionPublication?.supported() || !previous.active && !previous.executions.size) {
+                previous.stateSink?.close();
+                previous.stateSink = undefined;
+            }
+        }
+    }
+    async observe(binding) {
+        let ready = false;
+        try {
+            for await (const item of binding.session.observe()) {
+                recordProtocolTrace({ stage: 'provider.observation', kind: item.type,
+                    correlation: { channelId: binding.channelId, agentId: binding.agentId, sessionId: binding.nativeId,
+                        taskId: binding.active?.taskId, turnId: binding.active?.turnId }, payload: item,
+                    outcome: item.type === 'history_boundary' ? 'boundary' : !ready ? 'history' : item.type !== 'observation' || item.delivery !== 'live' ? 'not_live' : !binding.active ? 'idle' : 'active' });
+                if (item.type === 'history_boundary') {
+                    ready = true;
+                    if (this.options.provider.descriptor.sessionObservation !== 'complete-state') {
+                        binding.ready.resolve();
+                        this.setAvailability(binding, 'available');
+                        this.publishBinding(binding, false);
+                        this.publishTimeline(binding);
+                        this.admitChildren(binding);
+                    }
+                    continue;
+                }
+                if (item.type === 'session_invalidated') {
+                    this.setAvailability(binding, item.recovery === 'retrying' ? 'recovering' : 'stopped', item.reason, true);
+                    binding.observationQueue = [];
+                    binding.observationBytes = 0;
+                    this.retireInteractions(binding);
+                    binding.ownership.retireObservations();
+                    binding.legacyOwnership?.retireObservations();
+                    continue;
+                }
+                if (item.type === 'observation' && (!ready || item.delivery !== 'live')) {
+                    binding.timeline.append(binding.legacyOwnership?.publicObservation(item) ?? item);
+                    binding.gate.accept(item);
+                    continue;
+                }
+                if (!ready)
+                    continue;
+                if (item.type === 'session_restored') {
+                    this.setAvailability(binding, 'recovering', 'restoring', true);
+                }
+                this.queueObservation(binding, item);
+            }
+            if (!binding.closed)
+                throw new Error('The native observation stream closed before the session was disposed.');
+        }
+        catch (error) {
+            binding.ready.reject(error);
+            this.setAvailability(binding, 'stopped', 'observation_ended', true);
+            binding.observationQueue = [];
+            binding.observationBytes = 0;
+            this.retireInteractions(binding);
+            binding.active?.result.reject(error);
+            for (const turn of binding.executions.values())
+                turn.result.reject(error);
+        }
+    }
+    queueObservation(binding, item) {
+        const bytes = Buffer.byteLength(JSON.stringify(item));
+        if (binding.observationQueue.length >= 4096 || binding.observationBytes + bytes > 4 * 1024 * 1024) {
+            binding.observationQueue = [];
+            binding.observationBytes = 0;
+            this.setAvailability(binding, 'stopped', 'observation_capacity', true);
+            this.retireInteractions(binding);
+            return;
+        }
+        binding.observationQueue.push({ item: structuredClone(item), revision: binding.observation.revision, bytes });
+        binding.observationBytes += bytes;
+        this.drainObservations(binding);
+    }
+    drainObservations(binding) {
+        if (binding.observationWork)
+            return;
+        binding.observationWork = Promise.resolve().then(async () => {
+            while (binding.observationQueue.length && !this.disposed && !binding.closed) {
+                const next = binding.observationQueue.shift();
+                binding.observationBytes -= next.bytes;
+                if (next.revision !== binding.observation.revision)
+                    continue;
+                try {
+                    if (next.item.type === 'session_restored')
+                        await this.restoreSession(binding, next.item, next.revision);
+                    else if (binding.observation.status === 'available')
+                        await this.processObservation(binding, next.item);
+                }
+                catch {
+                    if (next.revision === binding.observation.revision && this.bindingCurrent(binding)) {
+                        this.setAvailability(binding, 'stopped', next.item.type === 'session_restored' ? 'invalid_native_snapshot' : 'observation_failed', true);
+                        this.retireInteractions(binding);
+                    }
+                }
+            }
+        }).finally(() => {
+            binding.observationWork = undefined;
+            if (binding.observationQueue.length && !this.disposed && !binding.closed)
+                this.drainObservations(binding);
+        });
+    }
+    async processObservation(binding, item) {
+        const revision = binding.observation.revision;
+        if (item.type === 'timeline_replacement') {
+            if (!binding.closed) {
+                const association = binding.projection.replaceHistory(item.observations.map(observation => binding.legacyOwnership?.publicObservation(observation) ?? observation));
+                if (association) {
+                    if (this.reconcileAssociationMetadata(binding, association))
+                        this.publishTimeline(binding);
+                    this.publishTimeline(binding);
+                }
+            }
+            return;
+        }
+        if (['turn_started', 'turn_completed', 'turn_failed', 'turn_canceled'].includes(item.event.type) && 'turnId' in item.event && item.event.turnId && binding.restoredTerminals?.has(item.event.turnId))
+            return;
+        const accepted = binding.gate.accept(item);
+        if (!accepted)
+            return;
+        let observation = accepted;
+        if (accepted.event.type === 'interaction_requested')
+            observation = { ...accepted, event: { ...accepted.event, request: publicHostInteraction(accepted.event.request) } };
+        else if (accepted.event.type === 'interaction_resolved') {
+            const request = binding.requests.get(accepted.event.requestId);
+            if (request?.kind === accepted.event.response.kind)
+                observation = { ...accepted, event: { ...accepted.event, response: redactInteractionResponse(request, accepted.event.response) } };
+        }
+        const legacyUser = binding.legacyOwnership && binding.executions.size > 0 && observation.event.type === 'timeline' && observation.event.item.type === 'user_message';
+        if (!legacyUser) {
+            observation = binding.legacyOwnership?.publicObservation(observation) ?? observation;
+            if (binding.legacyOwnership)
+                binding.timeline.append(observation);
+        }
+        const projected = binding.legacyOwnership ? undefined : binding.projection.observeLive(observation);
+        observation = projected?.publicObservation ?? observation;
+        const nativeTurnChanged = this.observeNativeTurn(binding, observation);
+        if (observation !== item)
+            recordProtocolTrace({ stage: 'host.normalized', kind: 'observation_conflict', correlation: { channelId: binding.channelId, agentId: binding.agentId, taskId: binding.active?.taskId }, outcome: 'diagnosed' });
+        const association = binding.legacyOwnership
+            ? { status: 'unchanged', correlations: [], unavailableOwners: [], owned: binding.legacyOwnership.observe(observation).map(value => ({ owner: value.owner.ownerId, observation: value.observation })) }
+            : projected.association;
+        const currentOwned = association.owned.find(value => value.observation.sourceKey === observation.sourceKey);
+        const currentTask = currentOwned && !legacyUser ? binding.projection.attributeOwned(currentOwned).taskId : undefined;
+        if (!legacyUser)
+            this.observeSessionState(binding, observation, currentTask);
+        await this.applyAssociation(binding, association);
+        if (binding.observation.revision !== revision || !this.bindingCurrent(binding))
+            return;
+        if (observation.event.type === 'runtime_updated')
+            this.observeEvent(binding, observation.event, observation);
+        if (binding.active && observation.event.type === 'interaction_resolved')
+            void this.finishLocalCommand(binding, binding.active);
+        if (!association.owned.length && nativeTurnChanged)
+            this.syncNormalizedActivity(binding.channelId, binding.bindingId);
+    }
+    bindingCapabilities(binding) {
+        return binding.restoredCapabilities ?? binding.session.capabilities;
+    }
+    retireInteractions(binding) {
+        binding.requests.clear();
+        binding.requestTasks?.clear();
+        for (const receipt of binding.receipts.values())
+            receipt.reject(new Error('Native interaction connection expired.'));
+        binding.receipts.clear();
+    }
+    observeNativeTurn(binding, observation) {
+        const event = observation.event;
+        if (event.type === 'turn_started' && event.turnId) {
+            binding.nativeActiveTurn = { turnId: event.turnId, startedAt: new Date(observation.occurredAt).toISOString() };
+            binding.status = 'running';
+            return true;
+        }
+        else if (['turn_completed', 'turn_failed', 'turn_canceled'].includes(event.type) && 'turnId' in event && event.turnId === binding.nativeActiveTurn?.turnId) {
+            binding.nativeActiveTurn = null;
+            binding.status = event.type === 'turn_failed' ? 'failed' : 'idle';
+            return true;
+        }
+        return false;
+    }
+    async restoreSession(binding, restored, revision) {
+        if (restored.runtimeInfo.sessionId !== binding.nativeId || restored.runtimeInfo.providerId !== this.options.provider.descriptor.providerId)
+            throw new Error('Native snapshot identity changed.');
+        const current = () => this.bindingCurrent(binding) && binding.observation.revision === revision;
+        const sources = new Set();
+        if (!Array.isArray(restored.observations) || !Array.isArray(restored.pendingInteractions)
+            || new Set(restored.pendingInteractions.map(request => request.requestId)).size !== restored.pendingInteractions.length)
+            throw new Error('Invalid native snapshot.');
+        for (const row of restored.observations) {
+            if (!row || row.type !== 'observation' || row.event.provider !== restored.runtimeInfo.providerId || !row.sourceKey || sources.has(row.sourceKey))
+                throw new Error('Invalid native snapshot.');
+            sources.add(row.sourceKey);
+        }
+        const { persistence: _snapshotPersistence, ...snapshotRuntime } = restored.runtimeInfo;
+        const snapshot = { protocolVersion: PROTOCOL_VERSION, type: 'agent_snapshot', payload: { id: binding.agentId, providerId: snapshotRuntime.providerId,
+                createdAt: binding.createdAt, updatedAt: new Date().toISOString(), status: snapshotRuntime.status, activeTurn: restored.activeTurn,
+                capabilities: restored.capabilities, runtimeInfo: this.visibleRuntime(binding, snapshotRuntime), pendingInteractions: restored.pendingInteractions.map(publicHostInteraction) } };
+        if (decodeAgentSnapshot(JSON.stringify(snapshot)).status !== 'ok')
+            throw new Error('Invalid native snapshot.');
+        const timeline = restored.observations.filter(observation => observation.event.type === 'timeline').map(observation => binding.legacyOwnership?.publicObservation(observation) ?? observation);
+        formatTimelineReplacement(timeline, { scope: binding.timeline.scope, inputs: binding.timeline.inputs, agentId: binding.agentId, channelId: binding.channelId });
+        if (Buffer.byteLength(JSON.stringify(timeline)) > 1024 * 1024)
+            throw new Error('Native snapshot exceeds capacity.');
+        this.retireInteractions(binding);
+        for (const observation of restored.observations)
+            binding.gate.accept(observation);
+        if (!binding.timeline.replace(timeline))
+            throw new Error('Invalid native history.');
+        binding.ownership.retireObservations();
+        binding.legacyOwnership?.retireObservations();
+        await this.applyAssociation(binding, binding.ownership.restoreHistory());
+        if (!current())
+            return;
+        const owners = [...binding.executions.values()];
+        const command = binding.active;
+        if (command?.commandSettled && command.expectsNativeTurn && command.commandTurnId && !owners.includes(command))
+            owners.push(command);
+        for (const turn of owners) {
+            if (turn.terminal || turn.isCurrent && !turn.isCurrent())
+                continue;
+            const turnId = binding.legacyOwnership?.recover(turn, restored.observations) ?? binding.ownership.turnId(turn.ownerId) ?? turn.commandTurnId;
+            if (!turnId || turn.turnId && turn.turnId !== turnId)
+                continue;
+            const evidence = restored.observations.filter(({ event }) => 'turnId' in event && event.turnId === turnId);
+            if (!evidence.length)
+                continue;
+            const started = evidence.find(({ event }) => event.type === 'turn_started');
+            if (!turn.started && !started)
+                continue;
+            if (binding.active && binding.active !== turn && !binding.active.terminal)
+                continue;
+            const messages = new Map();
+            let completeMessages = true;
+            for (const { event } of evidence) {
+                if (event.type !== 'timeline' || event.item.type !== 'assistant_message' && event.item.type !== 'questionnaire')
+                    continue;
+                if (!event.item.messageId) {
+                    completeMessages = false;
+                    break;
+                }
+                messages.set(event.item.messageId, event.item.type === 'questionnaire' ? questionnaireReplyText(event.item) : event.item.text);
+            }
+            if (!completeMessages)
+                continue;
+            turn.turnId = turnId;
+            turn.messages = messages;
+            if (!turn.started && started)
+                await this.observeOwned(binding, turn, started);
+            if (!current())
+                return;
+            if (turn.terminal)
+                continue;
+            const terminal = [...evidence].reverse().find(({ event }) => ['turn_completed', 'turn_failed', 'turn_canceled'].includes(event.type));
+            if (terminal && restored.activeTurn?.turnId !== turnId) {
+                const event = terminal.event.type === 'turn_completed'
+                    ? { type: terminal.event.type, provider: terminal.event.provider, turnId } : terminal.event;
+                await this.observeOwned(binding, turn, { ...terminal, event });
+                if (!current())
+                    return;
+            }
+        }
+        if (!current())
+            return;
+        const { persistence: _persistence, ...runtimeInfo } = structuredClone(restored.runtimeInfo);
+        binding.restoredCapabilities = structuredClone(restored.capabilities);
+        binding.restoredTerminals = new Set(restored.observations.flatMap(({ event }) => ['turn_completed', 'turn_failed', 'turn_canceled'].includes(event.type)
+            && 'turnId' in event && event.turnId && event.turnId !== restored.activeTurn?.turnId ? [event.turnId] : []));
+        binding.timeline.replace(restored.observations.filter(observation => observation.event.type === 'timeline').map(observation => binding.legacyOwnership?.publicObservation(observation) ?? observation));
+        binding.runtime = { type: 'observation', delivery: 'live', sourceKey: `runtime:${randomUUID()}`, occurredAt: Date.now(),
+            event: { type: 'runtime_updated', provider: this.options.provider.descriptor.providerId, runtimeInfo } };
+        binding.nativeActiveTurn = structuredClone(restored.activeTurn);
+        binding.status = runtimeInfo.status;
+        binding.updatedAt = new Date().toISOString();
+        binding.requests = new Map(restored.pendingInteractions.map(request => [request.requestId, structuredClone(request)]));
+        binding.requestTasks = new Map(restored.pendingInteractions.map(request => [request.requestId, undefined]));
+        binding.ready.resolve();
+        this.setAvailability(binding, 'available');
+        for (const queued of binding.observationQueue)
+            if (queued.revision === revision)
+                queued.revision = binding.observation.revision;
+        this.syncNormalizedActivity(binding.channelId, binding.bindingId);
+        this.admitChildren(binding);
+    }
+    observeEvent(binding, event, observation) {
+        binding.updatedAt = new Date(observation?.occurredAt ?? Date.now()).toISOString();
+        if (event.type === 'runtime_updated') {
+            binding.restoredCapabilities = undefined;
+            const { persistence: _persistence, ...runtimeInfo } = event.runtimeInfo;
+            event = { ...event, runtimeInfo: this.visibleRuntime(binding, runtimeInfo) };
+            if (observation) {
+                const previous = binding.runtime?.event.type === 'runtime_updated' ? binding.runtime.event.runtimeInfo.childSessions : undefined;
+                const relationsChanged = JSON.stringify(previous) !== JSON.stringify(runtimeInfo.childSessions);
+                observation = { ...observation, event };
+                binding.runtime = observation;
+                this.admitChildren(binding, relationsChanged);
+            }
+            binding.status = runtimeInfo.status;
+            this.publishBinding(binding, false);
+            if ((!binding.active || binding.active.terminal) && observation && !binding.closed && this.bindings.get(binding.channelId) === binding) {
+                recordProtocolTrace({ stage: 'host.normalized', kind: event.type, correlation: { channelId: binding.channelId, agentId: binding.agentId }, payload: event, outcome: 'idle_state' });
+                try {
+                    binding.stateSink?.observe(observation, binding.agentId, structuredClone(this.bindingCapabilities(binding)), binding.bindingId, binding.timeline.epoch);
+                    this.publishTimeline(binding);
+                }
+                catch { /* Idle publication cannot reopen an execution. */ }
+                return;
+            }
+        }
+        const turn = binding.active;
+        const rejected = (reason) => recordProtocolTrace({ stage: 'host.normalized', kind: event.type,
+            correlation: { channelId: binding.channelId, agentId: binding.agentId, taskId: turn?.taskId, turnId: turn?.turnId },
+            payload: event, outcome: 'rejected', reason });
+        if (!turn || turn.terminal)
+            return;
+        if (turn.isCurrent && !turn.isCurrent()) {
+            turn.result.reject(new ProviderTurnCancelledError('Native Session connection ownership ended.'));
+            return;
+        }
+        if (event.type === 'turn_started') {
+            if (turn.turnId && event.turnId !== turn.turnId) {
+                rejected('turn_mismatch');
+                return;
+            }
+            if (!turn.started)
+                turn.startedAt = new Date(observation?.occurredAt ?? Date.now()).toISOString();
+            turn.started = true;
+            turn.turnId = event.turnId;
+            binding.status = 'running';
+        }
+        if ('turnId' in event && event.turnId && turn.turnId && event.turnId !== turn.turnId) {
+            rejected('turn_mismatch');
+            return;
+        }
+        let publicEvent = event;
+        if (event.type === 'timeline' && event.item.type === 'user_message') {
+            if (observation) {
+                const row = formatTimelineReplacement([observation], { scope: binding.timeline.scope, inputs: binding.timeline.inputs, agentId: binding.agentId, channelId: binding.channelId })[0];
+                publicEvent = { ...event, item: row.event.item };
+            }
+        }
+        else if (event.type === 'interaction_requested') {
+            publicEvent = { ...event, request: publicHostInteraction(event.request) };
+        }
+        else if (event.type === 'runtime_updated') {
+            const { persistence: _persistence, ...runtimeInfo } = event.runtimeInfo;
+            publicEvent = { ...event, runtimeInfo };
+        }
+        if (event.type === 'turn_completed' || event.type === 'turn_failed' || event.type === 'turn_canceled') {
+            turn.terminal = true;
+            binding.status = event.type === 'turn_failed' ? 'failed' : 'idle';
+        }
+        if (observation && event.type === 'timeline')
+            binding.timeline.inputs.attribute(binding.timeline.scope, observation.sourceKey, turn.taskId);
+        recordProtocolTrace({ stage: 'host.normalized', kind: publicEvent.type,
+            correlation: { channelId: binding.channelId, agentId: binding.agentId, taskId: turn.taskId, turnId: turn.turnId }, payload: publicEvent });
+        try {
+            const metadata = observation ? { ...observation, event: publicEvent } : undefined;
+            if (publicEvent.type === 'runtime_updated')
+                turn.options?.onNormalizedObservation?.(publicEvent, binding.agentId, metadata, structuredClone(this.bindingCapabilities(binding)), binding.bindingId, binding.timeline.epoch);
+            else if (observation && (this.sessionPublication?.supported() || binding.publisher?.hasTimelineSource(observation)))
+                turn.options?.onNormalizedObservation?.(publicEvent, binding.agentId, metadata, undefined, binding.bindingId, binding.timeline.epoch, true);
+            else
+                turn.options?.onNormalizedObservation?.(publicEvent, binding.agentId, metadata, undefined, binding.bindingId, binding.timeline.epoch);
+        }
+        catch { /* Presentation cannot settle a durable turn. */ }
+        if (event.type === 'interaction_resolved' || event.type === 'runtime_updated')
+            void this.finishLocalCommand(binding, turn);
+        if (event.type === 'timeline' && (event.item.type === 'assistant_message' || event.item.type === 'questionnaire') && turn.started) {
+            const key = event.item.messageId ?? 'assistant';
+            turn.messages.set(key, event.item.type === 'questionnaire' ? questionnaireReplyText(event.item) : (turn.messages.get(key) ?? '') + event.item.text);
+            try {
+                turn.options?.onProgress?.({ type: 'text', stream: 'answer', text: [...turn.messages.values()].join('\n\n'), messageId: key });
+            }
+            catch { /* Draft delivery is best-effort. */ }
+        }
+        else if (event.type === 'turn_completed' && turn.started) {
+            turn.result.resolve({ ...parseProviderReply([...turn.messages.values()].join('\n\n')), sessionId: binding.nativeId });
+        }
+        else if (event.type === 'turn_failed')
+            turn.result.reject(new Error(event.error));
+        else if (event.type === 'turn_canceled')
+            turn.result.reject(new ProviderTurnCancelledError(event.reason));
+    }
+    async respondInteraction(input, context) {
+        const binding = this.controlBinding(input.channelId, input.binding?.binding_id);
+        const revision = binding?.observation.revision;
+        const current = () => !!binding && this.bindingCurrent(binding) && binding.observation.status === 'available' && binding.observation.revision === revision && (!context || !context.signal.aborted && (context.isConnectionCurrent?.() ?? true));
+        const active = binding?.active && !binding.active.terminal && (binding.nativeActiveTurn === undefined || binding.nativeActiveTurn?.turnId === binding.active.turnId) ? binding.active : undefined;
+        const requestTask = binding?.requestTasks?.get(input.requestId);
+        if (!binding || !current() || binding.agentId !== input.agentId || input.binding && (!this.sessionPublication?.supported() || binding.nativeId !== input.binding.native_session_id)
+            || !binding.requestTasks?.has(input.requestId) || (input.taskId ? requestTask !== input.taskId : !input.binding || !this.sessionPublication?.supported()))
+            throw new Error('The native interaction does not belong to this Host Session request.');
+        const request = binding.requests.get(input.requestId);
+        if (!request || request.kind !== input.response.kind || binding.receipts.has(input.requestId))
+            throw new Error('The native interaction is stale or already being answered.');
+        assertHostedInteractionScope(input.response);
+        const receipt = deferred();
+        binding.receipts.set(input.requestId, receipt);
+        const timeout = setTimeout(() => receipt.reject(new Error('Native interaction receipt timed out.')), 10_000);
+        try {
+            const [, confirmed] = await Promise.all([binding.session.respondToInteraction(input.requestId, input.response), receipt.promise]);
+            if (!current())
+                throw new Error('Native interaction connection ownership ended.');
+            if (active && binding.active === active && !active.terminal)
+                await this.finishLocalCommand(binding, active);
+            return confirmed;
+        }
+        finally {
+            clearTimeout(timeout);
+            if (binding.receipts.get(input.requestId) === receipt)
+                binding.receipts.delete(input.requestId);
+        }
+    }
+    /** Capture and publication share the observation loop's synchronous ordering. */
+    syncNormalizedActivity(channelId, bindingId) {
+        const binding = this.controlBinding(channelId, bindingId);
+        if (!binding || binding.closed || binding.runtime?.event.type !== 'runtime_updated')
+            return false;
+        if (binding.observation.status !== 'available') {
+            this.publishAvailability(binding);
+            return false;
+        }
+        this.admitChildren(binding);
+        if (!bindingId && this.sessionPublication?.supported())
+            for (const record of this.bindingRecords.values())
+                if (record.channelId === channelId && record !== binding)
+                    this.publishBinding(record, false);
+        const declared = this.publishBinding(binding, !bindingId);
+        if (!binding.stateSink?.snapshot && !this.sessionPublication?.supported())
+            return declared;
+        const active = binding.active && !binding.active.terminal ? binding.active : undefined;
+        const pendingInteractions = [...binding.requests.values()].map(publicHostInteraction);
+        const nativeActive = binding.nativeActiveTurn;
+        const status = pendingInteractions.length ? 'waiting' : nativeActive !== undefined ? binding.status : active ? (active.started ? 'running' : 'starting') : binding.status;
+        const snapshot = { protocolVersion: PROTOCOL_VERSION, type: 'agent_snapshot', payload: {
+                id: binding.agentId, providerId: this.options.provider.descriptor.providerId,
+                createdAt: binding.createdAt, updatedAt: binding.updatedAt, status,
+                activeTurn: nativeActive !== undefined ? nativeActive : active?.turnId ? { turnId: active.turnId, startedAt: active.startedAt } : null,
+                capabilities: structuredClone(this.bindingCapabilities(binding)), pendingInteractions,
+                runtimeInfo: { ...structuredClone(binding.runtime.event.runtimeInfo), sessionId: binding.nativeId, status },
+            } };
+        const sessionScoped = this.sessionPublication?.supported() === true;
+        const stateSynced = !sessionScoped && (binding.stateSink?.snapshot?.(snapshot, binding.bindingId, binding.timeline.epoch) ?? false);
+        const synced = stateSynced || declared;
+        if (sessionScoped) {
+            const taskId = binding.publicationTaskId;
+            // A complete Session snapshot can contain requests owned by different executions.
+            binding.publicationTaskId = undefined;
+            try {
+                this.publisher(binding).publish(snapshot, Date.now(), this.options.provider.descriptor.providerId, this.bindingCapabilities(binding), binding.bindingId, binding.timeline.epoch);
+            }
+            finally {
+                binding.publicationTaskId = taskId;
+            }
+        }
+        if (synced)
+            this.publishTimeline(binding);
+        return synced;
+    }
+    async cancelTurn(channelId, target, context) {
+        const binding = this.controlBinding(channelId, target?.binding_id);
+        if (target && (!this.sessionPublication?.supported() || binding?.nativeId !== target.native_session_id) || context && (context.signal.aborted || context.isConnectionCurrent && !context.isConnectionCurrent()))
+            return false;
+        if (!binding || binding.closed || binding.observation.status !== 'available' || !this.bindingCapabilities(binding).cancel || !binding.session.cancel || !binding.active && !['running', 'waiting', 'starting'].includes(binding.status))
+            return false;
+        await binding.session.cancel();
+        return true;
+    }
+    async interruptTurn(channelId) { return this.cancelTurn(channelId); }
+    async cancelSession(channelId) { return this.cancelTurn(channelId); }
+    closeBinding(binding) {
+        binding.closing ??= this.disposeBinding(binding);
+        return binding.closing;
+    }
+    async disposeBinding(binding) {
+        this.setAvailability(binding, 'stopped', 'session_closed', true);
+        binding.closed = true;
+        binding.observationQueue = [];
+        binding.observationBytes = 0;
+        await binding.admitting;
+        binding.publisher?.close();
+        binding.ownership.dispose();
+        binding.closed = true;
+        if (binding.active?.started && !binding.active.terminal)
+            this.observeEvent(binding, { type: 'turn_canceled', provider: this.options.provider.descriptor.providerId, turnId: binding.active.turnId, reason: 'Native session closed.' });
+        binding.active?.result.reject(new ProviderTurnCancelledError('Native session closed.'));
+        for (const turn of binding.executions.values())
+            turn.result.reject(new ProviderTurnCancelledError('Native session closed.'));
+        for (const receipt of binding.receipts.values())
+            receipt.reject(new Error('Native session closed.'));
+        binding.stateSink?.close();
+        binding.stateSink = undefined;
+        try {
+            await binding.session.dispose();
+            await binding.pump;
+        }
+        finally {
+            if (this.bindings.get(binding.channelId) === binding)
+                this.bindings.delete(binding.channelId);
+            this.bindingRecords.delete(binding.bindingId);
+        }
+    }
+    async dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        const closed = await Promise.allSettled([...this.bindingRecords.values()].map((binding) => this.closeBinding(binding)));
+        this.deferredRelations.clear();
+        await this.options.provider.dispose?.();
+        const failed = closed.find((result) => result.status === 'rejected');
+        if (failed?.status === 'rejected')
+            throw failed.reason;
+    }
+}
+function resolveAdditionalDirectories(turn) {
+    const context = turn.promptContext;
+    const directories = new Set();
+    if (context?.channelContextPayloadPath)
+        directories.add(dirname(context.channelContextPayloadPath));
+    if (context?.gatewayCredentialPath)
+        directories.add(dirname(context.gatewayCredentialPath));
+    if (context?.skillRuntime?.skillDirectoryPath)
+        directories.add(context.skillRuntime.skillDirectoryPath);
+    return [...directories].sort((left, right) => left.localeCompare(right));
+}