@xenosystem/agent-interface-host 0.1.7 → 0.1.8

package/dist/provider/ProviderLaneService.js

@@ -0,0 +1,892 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { existsSync, realpathSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { ProviderWriterLeaseService } from '../lease/ProviderWriterLeaseService.js';
+import { ProviderTransitionOutboxDispatcher, } from './ProviderTransitionOutboxDispatcher.js';
+const HOST_STATE_KEY = '__xenoHost';
+const BLOCKING_HANDOFF_STATUSES = new Set(['externally_advanced', 'needs_reconciliation']);
+/**
+ * Host authority for conversation workspace epochs and redacted provider lanes.
+ * Provider continuation locators never leave the repository's protected path.
+ */
+export class ProviderLaneService {
+    options;
+    now;
+    createId;
+    writerLeases;
+    eventSink;
+    nativeTerminals = new Map();
+    nativeTerminalByLane = new Map();
+    outboxDispatcher;
+    constructor(options) {
+        this.options = options;
+        if (!options.hostStorageIdentity.trim())
+            throw new Error('hostStorageIdentity is required.');
+        this.now = options.now ?? (() => new Date());
+        this.createId = options.createId ?? randomUUID;
+        this.writerLeases = options.writerLeaseService ?? (options.hostInstanceId
+            ? new ProviderWriterLeaseService({
+                store: options.repository.providerLanes,
+                hostInstanceId: options.hostInstanceId,
+                now: this.now,
+            })
+            : undefined);
+        this.outboxDispatcher = options.runtimeEventRepository
+            ? new ProviderTransitionOutboxDispatcher({
+                store: options.repository.providerLanes,
+                runtimeEvents: options.runtimeEventRepository,
+                onCommitted: (event) => this.eventSink?.('runtime.event.appended', {
+                    requestId: event.requestId,
+                    event,
+                }),
+            })
+            : undefined;
+    }
+    getHostBinding(conversationId) {
+        this.requireHostState(conversationId);
+        return {
+            schemaVersion: 1,
+            conversationId,
+            hostStorageIdentity: this.options.hostStorageIdentity,
+        };
+    }
+    setEventSink(sink) {
+        this.eventSink = sink;
+    }
+    start() {
+        void this.outboxDispatcher?.dispatchPending();
+    }
+    async openConversation(input) {
+        try {
+            const conversationId = boundedId(input.conversationId ?? this.createId(), 'conversationId');
+            const mode = input.mode ?? 'chat';
+            const existing = this.options.repository.loadConversationForHost(conversationId);
+            const workspace = this.resolveWorkspace(conversationId, mode, input.workingDirectory);
+            const previousHostState = readHostState(existing?.[HOST_STATE_KEY]);
+            const workspaceEpoch = previousHostState
+                && previousHostState.mode === mode
+                && previousHostState.workspaceEpoch.fingerprint === workspace.fingerprint
+                ? previousHostState.workspaceEpoch
+                : this.createWorkspaceEpoch(mode, workspace.directory, workspace.fingerprint);
+            const hostState = {
+                schemaVersion: 1,
+                hostStorageIdentity: this.options.hostStorageIdentity,
+                mode,
+                workspaceEpoch,
+                workspaceDirectory: workspace.directory,
+                ...(input.workspaceId ? { workspaceId: boundedId(input.workspaceId, 'workspaceId') } : {}),
+            };
+            const conversation = {
+                ...(existing ?? {}),
+                id: conversationId,
+                workspaceMode: mode === 'chat' ? 'chat-only' : 'workspace',
+                ...(mode === 'development'
+                    ? { rootDirectory: workspace.directory, grantedDirectories: [workspace.directory] }
+                    : { rootDirectory: undefined, grantedDirectories: [] }),
+                [HOST_STATE_KEY]: hostState,
+            };
+            const saved = this.options.repository.saveConversationForHost(conversation);
+            if (!saved.success)
+                return failure('CONVERSATION_NOT_FOUND', saved.error || 'Conversation could not be persisted.');
+            return this.conversationResult(conversationId, hostState);
+        }
+        catch (error) {
+            return failureFromError(error);
+        }
+    }
+    async resumeConversation(input) {
+        try {
+            const conversationId = boundedId(input.conversationId, 'conversationId');
+            const conversation = this.options.repository.loadConversationForHost(conversationId);
+            const hostState = readHostState(conversation?.[HOST_STATE_KEY]);
+            if (!conversation || !hostState || hostState.hostStorageIdentity !== this.options.hostStorageIdentity) {
+                return failure('CONVERSATION_NOT_FOUND', 'Conversation is not bound to this host storage authority.');
+            }
+            if (input.expectedWorkspaceEpochId && input.expectedWorkspaceEpochId !== hostState.workspaceEpoch.id) {
+                return failure('WORKSPACE_EPOCH_CONFLICT', 'Conversation workspace changed before resume.');
+            }
+            return this.conversationResult(conversationId, hostState);
+        }
+        catch (error) {
+            return failureFromError(error);
+        }
+    }
+    async listLanes(input) {
+        try {
+            const conversationId = boundedId(input.conversationId, 'conversationId');
+            const hostState = this.requireHostState(conversationId);
+            const lanes = this.options.repository.providerLanes.listLaneProjections(conversationId, input.includeHistorical !== false);
+            const activeLaneId = lanes.find((lane) => lane.workspaceEpoch.id === hostState.workspaceEpoch.id
+                && this.options.repository.providerLanes.getLane(lane.laneId)?.isActive)?.laneId;
+            return { success: true, conversationId, ...(activeLaneId ? { activeLaneId } : {}), lanes };
+        }
+        catch (error) {
+            return failureFromError(error);
+        }
+    }
+    async getLane(input) {
+        try {
+            const conversationId = boundedId(input.conversationId, 'conversationId');
+            this.requireHostState(conversationId);
+            const lane = this.options.repository.providerLanes.getLaneProjection(conversationId, boundedId(input.laneId, 'laneId'));
+            return lane
+                ? { success: true, conversationId, lane }
+                : failure('CONVERSATION_NOT_FOUND', 'Provider lane was not found.');
+        }
+        catch (error) {
+            return failureFromError(error);
+        }
+    }
+    async selectLane(input) {
+        try {
+            const conversationId = boundedId(input.conversationId, 'conversationId');
+            const requestHash = hashCanonical({
+                scope: 'provider.lanes.select',
+                conversationId,
+                providerId: input.providerId,
+                catalogRevision: input.catalogRevision,
+                modelId: input.modelId ?? null,
+                laneId: input.laneId ?? null,
+                expectedLaneRevision: input.expectedLaneRevision ?? null,
+                expectedWorkspaceEpochId: input.expectedWorkspaceEpochId ?? null,
+            });
+            const replay = this.options.repository.providerLanes.replayIdempotency(input.command.idempotencyKey, requestHash);
+            if (replay.found) {
+                return replay.conflict
+                    ? failure('LANE_REVISION_CONFLICT', 'Idempotency key was already used for a different provider selection.')
+                    : replay.response;
+            }
+            const hostState = this.requireHostState(conversationId);
+            if (input.expectedWorkspaceEpochId && input.expectedWorkspaceEpochId !== hostState.workspaceEpoch.id) {
+                return failure('WORKSPACE_EPOCH_CONFLICT', 'Conversation workspace changed before provider selection.');
+            }
+            const providers = await this.options.getProviders();
+            const provider = providers.find((candidate) => candidate.id === input.providerId);
+            if (!provider)
+                return failure('PROVIDER_UNAVAILABLE', 'Selected provider is not in the current catalog.');
+            if (provider.catalogRevision !== input.catalogRevision) {
+                return failure('CATALOG_REVISION_CONFLICT', 'Provider catalog changed before selection.');
+            }
+            if (provider.availability !== 'available' && provider.availability !== 'degraded') {
+                return failure('PROVIDER_UNAVAILABLE', provider.safeUnavailableReason || 'Selected provider is unavailable.');
+            }
+            const model = resolveModel(provider, input.modelId);
+            if ('code' in model)
+                return failure(model.code, model.error);
+            const compatibilityKey = resumeCompatibilityKey(provider, model.value?.id);
+            const lanes = this.options.repository.providerLanes.listLaneProjections(conversationId, true);
+            const requestedLane = input.laneId
+                ? lanes.find((lane) => lane.laneId === input.laneId)
+                : lanes.find((lane) => isReusableLane(lane, provider.id, model.value?.id, compatibilityKey, hostState.workspaceEpoch.id));
+            if (input.laneId && !requestedLane) {
+                return failure('CONVERSATION_NOT_FOUND', 'Requested provider lane was not found.');
+            }
+            if (requestedLane && !isReusableLane(requestedLane, provider.id, model.value?.id, compatibilityKey, hostState.workspaceEpoch.id)) {
+                return failure('MODEL_RESUME_INCOMPATIBLE', 'Requested lane is not compatible with this provider, model, or workspace epoch.');
+            }
+            const active = this.options.repository.providerLanes.getActiveLane(conversationId);
+            if (active && active.laneId !== requestedLane?.laneId && BLOCKING_HANDOFF_STATUSES.has(active.status)) {
+                return failure('RECONCILIATION_REQUIRED', 'The active provider lane must be reconciled before switching providers.');
+            }
+            if (requestedLane && input.laneId && input.expectedLaneRevision === undefined) {
+                return failure('LANE_REVISION_CONFLICT', 'expectedLaneRevision is required when selecting an existing lane.');
+            }
+            if (requestedLane && input.expectedLaneRevision !== undefined && input.expectedLaneRevision !== requestedLane.revision) {
+                return failure('LANE_REVISION_CONFLICT', 'Provider lane revision changed before selection.');
+            }
+            if (!requestedLane && input.expectedLaneRevision !== undefined && input.expectedLaneRevision !== 0) {
+                return failure('LANE_REVISION_CONFLICT', 'A new provider lane requires expectedLaneRevision 0 or no revision.');
+            }
+            const timestamp = this.now().toISOString();
+            const laneId = requestedLane?.laneId ?? `lane-${this.createId()}`;
+            const nextRevision = requestedLane ? requestedLane.revision + 1 : 1;
+            const existingRecord = requestedLane
+                ? this.options.repository.providerLanes.getLane(requestedLane.laneId, true)
+                : null;
+            const lane = {
+                ...(existingRecord ?? {}),
+                schemaVersion: 1,
+                laneId,
+                conversationId,
+                runtimeProviderId: provider.id,
+                providerKind: provider.kind,
+                providerDisplayName: provider.displayName,
+                ...(model.value ? { modelId: model.value.id, modelDisplayName: model.value.displayName } : {}),
+                resumeCompatibilityKey: compatibilityKey,
+                workspaceEpoch: hostState.workspaceEpoch,
+                status: existingRecord?.status ?? requestedLane?.status ?? 'new',
+                revision: requestedLane?.revision ?? 0,
+                isActive: true,
+                ...(provider.providerSession ? { capabilities: provider.providerSession } : {}),
+                lastRequestId: input.command.commandId,
+                lastUsedAt: timestamp,
+                createdAt: existingRecord?.createdAt ?? timestamp,
+                updatedAt: timestamp,
+            };
+            const projection = projectionForRevision(lane, nextRevision);
+            const response = { success: true, conversationId, lane: projection };
+            const result = this.options.repository.providerLanes.commitLaneTransition({
+                lane,
+                expectedRevision: requestedLane?.revision ?? 0,
+                outbox: {
+                    outboxId: `outbox-${this.createId()}`,
+                    conversationId,
+                    laneId,
+                    laneRevision: nextRevision,
+                    transitionType: 'provider.lane.selected',
+                    eventId: `provider-lane-selected-${input.command.commandId}`,
+                    idempotencyKey: input.command.idempotencyKey,
+                    payload: {
+                        id: `provider-lane-selected-${input.command.commandId}`,
+                        type: 'provider.lane.selected',
+                        timestamp,
+                        lane: projection,
+                    },
+                },
+                idempotency: {
+                    idempotencyKey: input.command.idempotencyKey,
+                    scope: 'provider.lanes.select',
+                    requestId: input.command.commandId,
+                    requestHash,
+                    laneId,
+                    conversationId,
+                    response: response,
+                },
+            });
+            if (!result.success)
+                return failure(result.code ?? 'LANE_REVISION_CONFLICT', result.error || 'Provider lane selection failed.');
+            void this.outboxDispatcher?.dispatchPending();
+            return result.replayed && result.response
+                ? result.response
+                : response;
+        }
+        catch (error) {
+            return failureFromError(error);
+        }
+    }
+    async attachNative(input) {
+        try {
+            const writerLeases = this.requireWriterLeases();
+            const conversationId = boundedId(input.conversationId, 'conversationId');
+            const laneId = boundedId(input.laneId, 'laneId');
+            const hostState = this.requireHostState(conversationId);
+            const lane = this.options.repository.providerLanes.getLane(laneId, true);
+            if (!lane || lane.conversationId !== conversationId || lane.workspaceEpoch.id !== hostState.workspaceEpoch.id) {
+                return failure('CONVERSATION_NOT_FOUND', 'Provider lane was not found for this workspace epoch.');
+            }
+            if (lane.revision !== input.expectedLaneRevision) {
+                return failure('LANE_REVISION_CONFLICT', 'Provider lane revision changed before native attach.');
+            }
+            if (lane.status === 'active_structured' || lane.status === 'active_native') {
+                return failure('LANE_WRITER_ACTIVE', 'Provider lane already has an active writer.');
+            }
+            if (lane.status === 'externally_advanced' || lane.status === 'needs_reconciliation') {
+                return failure('RECONCILIATION_REQUIRED', 'Provider lane must be reconciled before native attach.');
+            }
+            const native = readNativeContinuation(lane.continuation);
+            if (!native)
+                return failure('NATIVE_TUI_UNSUPPORTED', 'Provider lane does not contain a native resumable session.');
+            if (!this.options.resolveNativeLauncher) {
+                return failure('NATIVE_TUI_UNSUPPORTED', 'Provider-owned native launcher resolution is unavailable.');
+            }
+            const timestamp = this.now().toISOString();
+            const lease = createWriterLease({
+                leaseId: `lease-${this.createId()}`,
+                lane,
+                nativeProviderId: native.providerId,
+                nativeSessionHash: hashText(native.nativeSessionId),
+                hostInstanceId: this.options.hostInstanceId ?? 'injected-writer-lease-service',
+                ownerSurface: input.command.client.surface,
+                workspaceEpochId: hostState.workspaceEpoch.id,
+                authoritySnapshotHash: hashCanonical({
+                    workspaceEpochId: hostState.workspaceEpoch.id,
+                    client: input.command.client,
+                    laneRevision: lane.revision,
+                }),
+                timestamp,
+            });
+            const acquired = writerLeases.acquireLease(lease);
+            if (!acquired.success || !acquired.lease) {
+                return failure(acquired.code ?? 'LANE_WRITER_UNKNOWN', acquired.error || 'Provider writer lease could not be acquired.');
+            }
+            const laneResult = this.options.repository.providerLanes.saveLane({
+                ...lane,
+                status: 'active_native',
+                nativeProviderId: native.providerId,
+                redactedNativeSessionHash: hashText(native.nativeSessionId),
+                lastRequestId: input.command.commandId,
+                lastUsedAt: timestamp,
+                updatedAt: timestamp,
+            }, lane.revision, true);
+            if (!laneResult.success || !laneResult.lane) {
+                releaseWriterLease(writerLeases, acquired.lease);
+                return failure(laneResult.code ?? 'LANE_REVISION_CONFLICT', laneResult.error || 'Provider lane changed before native attach.');
+            }
+            const started = await this.options.workspaceService.startPty({
+                client: input.command.client,
+                conversationId,
+                cwd: hostState.workspaceDirectory,
+                allowedDirectories: [hostState.workspaceDirectory],
+                ...(input.cols === undefined ? {} : { cols: input.cols }),
+                ...(input.rows === undefined ? {} : { rows: input.rows }),
+                profile: {
+                    kind: 'provider-session',
+                    laneId,
+                    expectedLaneRevision: laneResult.lane.revision,
+                },
+            });
+            if (!started.success || !started.terminalId) {
+                releaseWriterLease(writerLeases, acquired.lease);
+                this.restoreLaneAfterFailedNativeStart(laneResult.lane);
+                return failure('NATIVE_TUI_UNSUPPORTED', started.error || 'Native provider TUI could not be started.');
+            }
+            const ownership = {
+                terminalId: started.terminalId,
+                conversationId,
+                laneId,
+                lease: acquired.lease,
+                ownerInstanceId: input.command.client.instanceId,
+            };
+            this.nativeTerminals.set(started.terminalId, ownership);
+            this.nativeTerminalByLane.set(laneId, started.terminalId);
+            this.startLeaseHeartbeat(ownership);
+            const result = {
+                success: true,
+                conversationId,
+                laneId,
+                terminalId: started.terminalId,
+                laneRevision: laneResult.lane.revision,
+            };
+            this.eventSink?.('provider.native_tui.started', {
+                conversationId,
+                laneId,
+                terminalId: started.terminalId,
+                laneRevision: laneResult.lane.revision,
+            });
+            return result;
+        }
+        catch (error) {
+            return failureFromError(error);
+        }
+    }
+    detachNative(input) {
+        try {
+            const conversationId = boundedId(input.conversationId, 'conversationId');
+            const laneId = boundedId(input.laneId, 'laneId');
+            const terminalId = input.terminalId || this.nativeTerminalByLane.get(laneId);
+            const ownership = terminalId ? this.nativeTerminals.get(terminalId) : undefined;
+            if (!ownership || ownership.conversationId !== conversationId || ownership.laneId !== laneId) {
+                return failure('CONVERSATION_NOT_FOUND', 'Active native provider terminal was not found.');
+            }
+            this.eventSink?.('provider.native_tui.detached', { conversationId, laneId, terminalId: ownership.terminalId });
+            return { success: true, conversationId, laneId };
+        }
+        catch (error) {
+            return failureFromError(error);
+        }
+    }
+    reattachNative(input) {
+        try {
+            const conversationId = boundedId(input.conversationId, 'conversationId');
+            const laneId = boundedId(input.laneId, 'laneId');
+            const terminalId = boundedId(input.terminalId, 'terminalId');
+            const ownership = this.nativeTerminals.get(terminalId);
+            if (!ownership || ownership.conversationId !== conversationId || ownership.laneId !== laneId) {
+                return failure('CONVERSATION_NOT_FOUND', 'Active native provider terminal was not found.');
+            }
+            if (!this.options.workspaceService.transferPtyOwnership(terminalId, input.command.client.instanceId)) {
+                return failure('LANE_WRITER_UNKNOWN', 'Native provider terminal ownership could not be transferred.');
+            }
+            ownership.ownerInstanceId = input.command.client.instanceId;
+            return { success: true, conversationId, laneId, terminalId };
+        }
+        catch (error) {
+            return failureFromError(error);
+        }
+    }
+    stopNative(input) {
+        try {
+            const conversationId = boundedId(input.conversationId, 'conversationId');
+            const laneId = boundedId(input.laneId, 'laneId');
+            const terminalId = input.terminalId || this.nativeTerminalByLane.get(laneId);
+            const ownership = terminalId ? this.nativeTerminals.get(terminalId) : undefined;
+            if (!ownership || ownership.conversationId !== conversationId || ownership.laneId !== laneId) {
+                return failure('CONVERSATION_NOT_FOUND', 'Active native provider terminal was not found.');
+            }
+            this.options.workspaceService.transferPtyOwnership(ownership.terminalId, input.command.client.instanceId);
+            const stopped = this.options.workspaceService.stopPty({
+                client: input.command.client,
+                terminalId: ownership.terminalId,
+                allowedDirectories: [],
+            });
+            return stopped.success
+                ? { success: true, conversationId, laneId, exited: false }
+                : failure('LANE_WRITER_UNKNOWN', stopped.error || 'Native provider terminal could not be stopped.');
+        }
+        catch (error) {
+            return failureFromError(error);
+        }
+    }
+    reconcile(input) {
+        try {
+            const conversationId = boundedId(input.conversationId, 'conversationId');
+            const laneId = boundedId(input.laneId, 'laneId');
+            const lane = this.options.repository.providerLanes.getLane(laneId, true);
+            if (!lane || lane.conversationId !== conversationId) {
+                return failure('CONVERSATION_NOT_FOUND', 'Provider lane was not found.');
+            }
+            if (lane.revision !== input.expectedLaneRevision) {
+                return failure('LANE_REVISION_CONFLICT', 'Provider lane revision changed before reconciliation.');
+            }
+            if (lane.status !== 'externally_advanced' && lane.status !== 'needs_reconciliation') {
+                return failure('RECONCILIATION_FAILED', 'Provider lane does not require reconciliation.');
+            }
+            if (!input.acknowledgePartialContext) {
+                return failure('RECONCILIATION_REQUIRED', 'Native provider history import is partial and must be acknowledged.');
+            }
+            const timestamp = this.now().toISOString();
+            const capsuleId = `handoff-${this.createId()}`;
+            const capsule = {
+                schemaVersion: 1,
+                id: capsuleId,
+                sourceRuntimeProviderId: lane.runtimeProviderId,
+                ...(lane.redactedNativeSessionHash ? { sourceNativeSessionHash: lane.redactedNativeSessionHash } : {}),
+                workspaceEpochId: lane.workspaceEpoch.id,
+                createdAt: timestamp,
+                summary: 'Native provider TUI exited. The exact provider session will resume; unstructured TUI-only context was not imported.',
+                decisions: [],
+                changedFiles: [],
+                commandsAndTests: [],
+                unresolvedIssues: ['TUI-only conversational context was not structurally imported.'],
+                nextActions: ['Resume the provider lane in chat and verify the workspace state.'],
+                completeness: 'partial',
+            };
+            const { invalidationReason: _invalidationReason, ...laneWithoutInvalidation } = lane;
+            const saved = this.options.repository.providerLanes.saveLane({
+                ...laneWithoutInvalidation,
+                status: 'clean',
+                lastHandoffCapsuleId: capsuleId,
+                lastRequestId: input.command.commandId,
+                lastUsedAt: timestamp,
+                updatedAt: timestamp,
+            }, lane.revision, true);
+            return saved.success && saved.projection
+                ? { success: true, conversationId, laneId, lane: saved.projection, capsule, acknowledgedPartial: true }
+                : failure(saved.code ?? 'RECONCILIATION_FAILED', saved.error || 'Provider lane reconciliation failed.');
+        }
+        catch (error) {
+            return failureFromError(error);
+        }
+    }
+    resolveProviderSessionPty = async (profile, cwd) => {
+        const lane = this.options.repository.providerLanes.getLane(profile.laneId, true);
+        if (!lane || lane.revision !== profile.expectedLaneRevision || lane.status !== 'active_native') {
+            return { code: 'LANE_REVISION_CONFLICT', error: 'Provider lane changed before native TUI launch.' };
+        }
+        const native = readNativeContinuation(lane.continuation);
+        if (!native || !this.options.resolveNativeLauncher) {
+            return { code: 'NATIVE_TUI_UNSUPPORTED', error: 'Provider lane has no provider-owned native launcher.' };
+        }
+        return this.options.resolveNativeLauncher({
+            runtimeProviderId: lane.runtimeProviderId,
+            nativeProviderId: native.providerId,
+            nativeSessionId: native.nativeSessionId,
+            cwd,
+        });
+    };
+    handleWorkspacePtyExit(payload) {
+        const terminalId = typeof payload.terminalId === 'string' ? payload.terminalId : '';
+        const ownership = this.nativeTerminals.get(terminalId);
+        if (!ownership)
+            return;
+        this.nativeTerminals.delete(terminalId);
+        this.nativeTerminalByLane.delete(ownership.laneId);
+        if (ownership.heartbeat)
+            clearInterval(ownership.heartbeat);
+        releaseWriterLease(this.requireWriterLeases(), ownership.lease);
+        const lane = this.options.repository.providerLanes.getLane(ownership.laneId, true);
+        if (lane?.status === 'active_native') {
+            const timestamp = this.now().toISOString();
+            this.options.repository.providerLanes.saveLane({
+                ...lane,
+                status: 'externally_advanced',
+                invalidationReason: 'Native provider TUI exited; reconcile before structured execution.',
+                lastUsedAt: timestamp,
+                updatedAt: timestamp,
+            }, lane.revision, true);
+        }
+        this.eventSink?.('provider.native_tui.exited', {
+            conversationId: ownership.conversationId,
+            laneId: ownership.laneId,
+            terminalId,
+            ...(typeof payload.exitCode === 'number' ? { exitCode: payload.exitCode } : {}),
+        });
+    }
+    close() {
+        for (const ownership of this.nativeTerminals.values()) {
+            if (ownership.heartbeat)
+                clearInterval(ownership.heartbeat);
+        }
+        this.nativeTerminals.clear();
+        this.nativeTerminalByLane.clear();
+    }
+    getWorkspaceDirectory(conversationId) {
+        return this.requireHostState(conversationId).workspaceDirectory;
+    }
+    requireWriterLeases() {
+        if (!this.writerLeases)
+            throw cockpitError('LANE_WRITER_UNKNOWN', 'Provider writer lease authority is unavailable.');
+        return this.writerLeases;
+    }
+    startLeaseHeartbeat(ownership) {
+        ownership.heartbeat = setInterval(() => {
+            const nextExpiry = new Date(this.now().valueOf() + 45_000).toISOString();
+            const renewed = this.requireWriterLeases().renewLease(ownership.lease.leaseId, ownership.laneId, ownership.lease.leaseRevision, nextExpiry);
+            if (renewed.success && renewed.lease)
+                ownership.lease = renewed.lease;
+        }, 15_000);
+        ownership.heartbeat.unref?.();
+    }
+    restoreLaneAfterFailedNativeStart(lane) {
+        const current = this.options.repository.providerLanes.getLane(lane.laneId, true);
+        if (!current || current.status !== 'active_native')
+            return;
+        const timestamp = this.now().toISOString();
+        this.options.repository.providerLanes.saveLane({
+            ...current,
+            status: 'clean',
+            updatedAt: timestamp,
+        }, current.revision, true);
+    }
+    prepareTurn(request) {
+        const hostState = this.requireHostState(request.conversationId);
+        if (request.mode !== hostState.mode) {
+            throw cockpitError('WORKSPACE_EPOCH_CONFLICT', 'Turn mode does not match the active conversation workspace epoch.');
+        }
+        const lane = this.options.repository.providerLanes.getActiveLane(request.conversationId, true);
+        if (!lane || lane.workspaceEpoch.id !== hostState.workspaceEpoch.id) {
+            throw cockpitError('CONVERSATION_BINDING_REQUIRED', 'Select a provider lane before starting a turn.');
+        }
+        if (lane.runtimeProviderId !== request.selection.providerId) {
+            throw cockpitError('MODEL_RESUME_INCOMPATIBLE', 'Turn provider does not match the active provider lane.');
+        }
+        if (lane.modelId && request.selection.modelId && lane.modelId !== request.selection.modelId) {
+            throw cockpitError('MODEL_RESUME_INCOMPATIBLE', 'Turn model does not match the active provider lane.');
+        }
+        if (lane.status === 'active_native') {
+            throw cockpitError('LANE_WRITER_ACTIVE', 'The provider lane is owned by a native TUI.');
+        }
+        if (lane.status === 'active_structured') {
+            throw cockpitError('LANE_WRITER_ACTIVE', 'The provider lane already has an active writer for a structured turn.');
+        }
+        if (lane.status === 'externally_advanced' || lane.status === 'needs_reconciliation') {
+            throw cockpitError('RECONCILIATION_REQUIRED', 'The provider lane must be reconciled before structured execution.');
+        }
+        const continuation = readContinuation(lane.continuation);
+        const prepared = structuredClone(request);
+        prepared.workspace = {
+            ...(request.workspace?.permissionProfile ? { permissionProfile: request.workspace.permissionProfile } : {}),
+            primaryDirectory: hostState.workspaceDirectory,
+            filesystem: request.workspace?.filesystem ?? 'workspace-write',
+        };
+        delete prepared.continuation;
+        if (continuation)
+            prepared.continuation = continuation;
+        return prepared;
+    }
+    beginStructuredTurn(request) {
+        const lane = this.options.repository.providerLanes.getActiveLane(request.conversationId, true);
+        if (!lane)
+            throw cockpitError('CONVERSATION_BINDING_REQUIRED', 'Active provider lane was not found.');
+        if (lane.status === 'active_native') {
+            throw cockpitError('LANE_WRITER_ACTIVE', 'The provider lane is owned by a native TUI.');
+        }
+        if (lane.status === 'active_structured') {
+            throw cockpitError('LANE_WRITER_ACTIVE', 'The provider lane already has an active writer for a structured turn.');
+        }
+        if (lane.status === 'externally_advanced' || lane.status === 'needs_reconciliation') {
+            throw cockpitError('RECONCILIATION_REQUIRED', 'The provider lane must be reconciled before structured execution.');
+        }
+        const timestamp = this.now().toISOString();
+        const saved = this.options.repository.providerLanes.saveLane({
+            ...lane,
+            status: 'active_structured',
+            lastRequestId: boundedId(request.requestId, 'requestId'),
+            lastUsedAt: timestamp,
+            updatedAt: timestamp,
+        }, lane.revision, true);
+        if (!saved.success)
+            throw cockpitError(saved.code ?? 'LANE_REVISION_CONFLICT', saved.error || 'Provider lane writer acquisition failed.');
+    }
+    finishStructuredTurn(conversationId, requestId) {
+        const lane = this.options.repository.providerLanes.getActiveLane(conversationId, true);
+        if (!lane || lane.status !== 'active_structured' || lane.lastRequestId !== requestId)
+            return;
+        const timestamp = this.now().toISOString();
+        this.options.repository.providerLanes.saveLane({
+            ...lane,
+            status: 'clean',
+            lastUsedAt: timestamp,
+            updatedAt: timestamp,
+        }, lane.revision, true);
+    }
+    commitTurnContinuation(input) {
+        try {
+            const hostState = this.requireHostState(input.conversationId);
+            const lane = this.options.repository.providerLanes.getActiveLane(input.conversationId, true);
+            if (!lane || lane.workspaceEpoch.id !== hostState.workspaceEpoch.id) {
+                return failure('CONVERSATION_BINDING_REQUIRED', 'Active provider lane was not found.');
+            }
+            const continuation = readContinuation(input.continuation);
+            if (!continuation || continuation.providerId !== lane.runtimeProviderId) {
+                return failure('CONTINUATION_INVALID', 'Provider continuation does not match the active lane.');
+            }
+            const timestamp = this.now().toISOString();
+            const result = this.options.repository.providerLanes.saveLane({
+                ...lane,
+                continuation,
+                continuationHash: hashCanonical(continuation),
+                status: lane.status === 'active_structured' ? 'active_structured' : 'clean',
+                lastRequestId: boundedId(input.requestId, 'requestId'),
+                lastUsedAt: timestamp,
+                updatedAt: timestamp,
+            }, lane.revision, true);
+            return result.success
+                ? { success: true, ...(result.projection ? { lane: result.projection } : {}) }
+                : failure(result.code ?? 'LANE_REVISION_CONFLICT', result.error || 'Provider continuation could not be committed.');
+        }
+        catch (error) {
+            return failureFromError(error);
+        }
+    }
+    conversationResult(conversationId, hostState) {
+        const lanes = this.options.repository.providerLanes.listLaneProjections(conversationId, true);
+        const activeLane = lanes.find((lane) => lane.workspaceEpoch.id === hostState.workspaceEpoch.id
+            && this.options.repository.providerLanes.getLane(lane.laneId)?.isActive);
+        return {
+            success: true,
+            conversationId,
+            hostStorageIdentity: this.options.hostStorageIdentity,
+            mode: hostState.mode,
+            workspaceEpoch: workspaceEpochProjection(hostState.workspaceEpoch),
+            ...(activeLane ? { activeLane } : {}),
+            lanes,
+        };
+    }
+    requireHostState(conversationId) {
+        const conversation = this.options.repository.loadConversationForHost(conversationId);
+        const hostState = readHostState(conversation?.[HOST_STATE_KEY]);
+        if (!conversation || !hostState || hostState.hostStorageIdentity !== this.options.hostStorageIdentity) {
+            throw cockpitError('CONVERSATION_NOT_FOUND', 'Conversation is not bound to this host storage authority.');
+        }
+        return hostState;
+    }
+    resolveWorkspace(conversationId, mode, requestedDirectory) {
+        if (mode === 'chat') {
+            const directory = this.options.workspaceService.ensureManagedConversationWorkspace(conversationId);
+            return { directory, fingerprint: workspaceFingerprint(mode, directory) };
+        }
+        if (!requestedDirectory?.trim())
+            throw cockpitError('WORKSPACE_REQUIRED', 'Agent mode requires a selected local folder.');
+        const absolute = resolve(requestedDirectory.trim());
+        if (!existsSync(absolute) || !statSync(absolute).isDirectory()) {
+            throw cockpitError('WORKSPACE_REQUIRED', 'Selected local folder does not exist.');
+        }
+        const directory = realpathSync.native(absolute);
+        return { directory, fingerprint: workspaceFingerprint(mode, directory) };
+    }
+    createWorkspaceEpoch(mode, directory, fingerprint) {
+        return {
+            id: `epoch-${this.createId()}`,
+            fingerprint,
+            wireMode: mode,
+            kind: mode === 'chat' ? 'private-chat' : 'local-workspace',
+            label: mode === 'chat' ? 'Private chat workspace' : directory,
+            allowedDirectoryFingerprints: [hashPath(directory)],
+        };
+    }
+}
+function resolveModel(provider, requestedModelId) {
+    const modelId = requestedModelId ?? provider.defaultModelId;
+    if (!modelId) {
+        return provider.allowsProviderDefaultModel
+            ? {}
+            : { code: 'PROVIDER_UNAVAILABLE', error: 'Selected provider requires an explicit model.' };
+    }
+    const model = provider.models.find((candidate) => candidate.id === modelId);
+    if (!model)
+        return { code: 'PROVIDER_UNAVAILABLE', error: 'Selected model is not in the current provider catalog.' };
+    if (model.availability !== 'available' && model.availability !== 'degraded') {
+        return { code: 'PROVIDER_UNAVAILABLE', error: model.safeUnavailableReason || 'Selected model is unavailable.' };
+    }
+    return { value: model };
+}
+function resumeCompatibilityKey(provider, modelId) {
+    const providerKey = provider.providerSession?.resumeCompatibilityKey?.trim() || `${provider.id}:provider-session-v1`;
+    const supportsModelSwitch = provider.providerSession?.modelSwitchInPlace?.status === 'available';
+    return supportsModelSwitch || !modelId ? providerKey : `${providerKey}:model=${modelId}`;
+}
+function isReusableLane(lane, providerId, modelId, compatibilityKey, workspaceEpochId) {
+    return lane.runtimeProviderId === providerId
+        && lane.workspaceEpoch.id === workspaceEpochId
+        && lane.resumeCompatibilityKey === compatibilityKey
+        && lane.modelId === modelId
+        && lane.status !== 'invalidated'
+        && lane.status !== 'error';
+}
+function projectionForRevision(lane, revision) {
+    return {
+        schemaVersion: 1,
+        laneId: lane.laneId,
+        conversationId: lane.conversationId,
+        runtimeProviderId: lane.runtimeProviderId,
+        providerKind: lane.providerKind,
+        ...(lane.providerDisplayName ? { providerDisplayName: lane.providerDisplayName } : {}),
+        ...(lane.modelId ? { modelId: lane.modelId } : {}),
+        ...(lane.modelDisplayName ? { modelDisplayName: lane.modelDisplayName } : {}),
+        resumeCompatibilityKey: lane.resumeCompatibilityKey,
+        workspaceEpoch: workspaceEpochProjection(lane.workspaceEpoch),
+        status: lane.status,
+        revision,
+        ...(lane.capabilities ? { capabilities: lane.capabilities } : {}),
+        ...(lane.lastUsedAt ? { lastUsedAt: lane.lastUsedAt } : {}),
+        ...(lane.lastRequestId ? { lastRequestId: lane.lastRequestId } : {}),
+    };
+}
+function workspaceEpochProjection(epoch) {
+    return {
+        id: epoch.id,
+        fingerprint: epoch.fingerprint,
+        wireMode: epoch.wireMode,
+        kind: epoch.kind,
+        ...(epoch.label ? { label: epoch.label } : {}),
+    };
+}
+function readHostState(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const record = value;
+    const epoch = record.workspaceEpoch;
+    if (record.schemaVersion !== 1
+        || typeof record.hostStorageIdentity !== 'string'
+        || (record.mode !== 'chat' && record.mode !== 'development')
+        || typeof record.workspaceDirectory !== 'string'
+        || !epoch || typeof epoch !== 'object' || Array.isArray(epoch))
+        return null;
+    const epochRecord = epoch;
+    if (typeof epochRecord.id !== 'string'
+        || typeof epochRecord.fingerprint !== 'string'
+        || (epochRecord.wireMode !== 'chat' && epochRecord.wireMode !== 'development')
+        || (epochRecord.kind !== 'private-chat' && epochRecord.kind !== 'local-workspace')
+        || !Array.isArray(epochRecord.allowedDirectoryFingerprints)
+        || !epochRecord.allowedDirectoryFingerprints.every((entry) => typeof entry === 'string'))
+        return null;
+    return structuredClone(record);
+}
+function readContinuation(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const record = value;
+    if (typeof record.providerId !== 'string' || !record.providerId.trim()
+        || typeof record.providerSessionId !== 'string' || !record.providerSessionId.trim())
+        return null;
+    if (record.state !== undefined && (!record.state || typeof record.state !== 'object' || Array.isArray(record.state))) {
+        return null;
+    }
+    for (const field of ['providerConfigFingerprint', 'workspaceFingerprint']) {
+        if (record[field] !== undefined && (typeof record[field] !== 'string' || !record[field].trim()))
+            return null;
+    }
+    return structuredClone(record);
+}
+function readNativeContinuation(value) {
+    const continuation = readContinuation(value);
+    const state = continuation?.state;
+    if (!state || state.schemaVersion !== 1
+        || typeof state.providerId !== 'string' || !state.providerId.trim()
+        || typeof state.nativeSessionId !== 'string' || !state.nativeSessionId.trim())
+        return null;
+    return { providerId: state.providerId.trim(), nativeSessionId: state.nativeSessionId.trim() };
+}
+function createWriterLease(input) {
+    const processStart = new Date(Date.now() - process.uptime() * 1_000).toISOString();
+    return {
+        schemaVersion: 1,
+        leaseId: input.leaseId,
+        laneId: input.lane.laneId,
+        laneRevision: input.lane.revision,
+        leaseRevision: 0,
+        conversationId: input.lane.conversationId,
+        hostInstanceId: input.hostInstanceId,
+        runtimeProviderId: input.lane.runtimeProviderId,
+        nativeProviderId: input.nativeProviderId,
+        nativeSessionHash: input.nativeSessionHash,
+        ownerSurface: input.ownerSurface,
+        ownerPid: process.pid,
+        ownerProcessStartTime: processStart,
+        ownerProcessIdentity: `${process.execPath}:${process.pid}`,
+        state: 'active',
+        acquiredAt: input.timestamp,
+        expiresAt: new Date(Date.parse(input.timestamp) + 45_000).toISOString(),
+        lastHeartbeatAt: input.timestamp,
+        workspaceEpochId: input.workspaceEpochId,
+        authoritySnapshotHash: input.authoritySnapshotHash,
+        createdAt: input.timestamp,
+        updatedAt: input.timestamp,
+    };
+}
+function releaseWriterLease(service, lease) {
+    const releasing = lease.state === 'releasing'
+        ? { success: true, lease }
+        : service.beginRelease(lease.leaseId, lease.laneId, lease.leaseRevision);
+    if (releasing.success && releasing.lease) {
+        service.confirmReleased(releasing.lease.leaseId, releasing.lease.laneId, releasing.lease.leaseRevision, true);
+    }
+}
+function hashText(value) {
+    return createHash('sha256').update(value, 'utf8').digest('hex');
+}
+function boundedId(value, label) {
+    const normalized = value.trim();
+    if (!normalized || normalized.length > 240 || normalized.includes('\0')) {
+        throw new Error(`${label} is invalid.`);
+    }
+    return normalized;
+}
+function workspaceFingerprint(mode, directory) {
+    return hashCanonical({ mode, directory: normalizedPath(directory) });
+}
+function hashPath(path) {
+    return createHash('sha256').update(normalizedPath(path), 'utf8').digest('hex');
+}
+function normalizedPath(path) {
+    const canonical = realpathSync.native(path);
+    return process.platform === 'win32' ? canonical.toLowerCase() : canonical;
+}
+function hashCanonical(value) {
+    return createHash('sha256').update(canonicalJson(value), 'utf8').digest('hex');
+}
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    if (value && typeof value === 'object') {
+        const record = value;
+        return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+function cockpitError(code, message) {
+    return Object.assign(new Error(message), { code });
+}
+function failure(code, error) {
+    return { success: false, code, error };
+}
+function failureFromError(error) {
+    const record = error;
+    const code = typeof record?.code === 'string' ? record.code : 'CONVERSATION_NOT_FOUND';
+    const message = typeof record?.message === 'string' && record.message.trim()
+        ? record.message.slice(0, 1_000)
+        : 'Provider lane operation failed.';
+    return failure(code, message);
+}
+//# sourceMappingURL=ProviderLaneService.js.map