@awcp/sdk 0.0.16 → 0.0.18

package/dist/delegator/service.js

@@ -5,167 +5,289 @@
  */
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
-import { DelegationStateMachine, createDelegation, applyMessageToDelegation, generateDelegationId, PROTOCOL_VERSION, AwcpError, WorkspaceTooLargeError, WorkspaceNotFoundError, WorkspaceInvalidError, } from '@awcp/core';
+import { DelegationStateMachine, isTerminalState, createDelegation, generateDelegationId, PROTOCOL_VERSION, AwcpError, WorkspaceNotFoundError, WorkspaceInvalidError, } from '@awcp/core';
 import { resolveDelegatorConfig } from './config.js';
 import { AdmissionController } from './admission.js';
-import { EnvironmentBuilder } from './environment-builder.js';
+import { DelegationManager } from './delegation-manager.js';
+import { EnvironmentManager } from './environment-manager.js';
 import { ExecutorClient } from './executor-client.js';
-import { SnapshotStore } from './snapshot-store.js';
+import { SnapshotManager } from './snapshot-manager.js';
 export class DelegatorService {
     config;
     transport;
     admissionController;
-    environmentBuilder;
-    snapshotStore;
+    delegationManager;
+    environmentManager;
+    snapshotManager;
     executorClient;
     delegations = new Map();
     stateMachines = new Map();
-    executorUrls = new Map();
     cleanupTimer;
     constructor(options) {
         this.config = resolveDelegatorConfig(options.config);
         this.transport = this.config.transport;
-        // liveSync transports don't support staged snapshots
-        if (this.transport.capabilities.liveSync && this.config.snapshot.mode === 'staged') {
-            this.config.snapshot.mode = 'auto';
+        if (this.transport.capabilities.liveSync && this.config.delegation.snapshot.mode === 'staged') {
+            this.config.delegation.snapshot.mode = 'auto';
         }
-        this.admissionController = new AdmissionController({
-            maxTotalBytes: this.config.admission.maxTotalBytes,
-            maxFileCount: this.config.admission.maxFileCount,
-            maxSingleFileBytes: this.config.admission.maxSingleFileBytes,
-        });
-        this.environmentBuilder = new EnvironmentBuilder({
+        this.admissionController = new AdmissionController(this.config.admission);
+        this.delegationManager = new DelegationManager({
             baseDir: path.join(this.config.baseDir, 'delegations'),
         });
-        this.snapshotStore = new SnapshotStore({
-            baseDir: this.config.baseDir,
+        this.environmentManager = new EnvironmentManager({
+            baseDir: path.join(this.config.baseDir, 'environments'),
+        });
+        this.snapshotManager = new SnapshotManager({
+            baseDir: path.join(this.config.baseDir, 'snapshots'),
+            transport: this.transport,
         });
-        this.executorClient = new ExecutorClient();
+        const { requestTimeout, sseMaxRetries, sseRetryDelayMs } = this.config.delegation.connection;
+        this.executorClient = new ExecutorClient(requestTimeout, sseMaxRetries, sseRetryDelayMs);
         this.startCleanupTimer();
     }
+    async initialize() {
+        await this.transport.initialize?.();
+        if (this.config.cleanupOnInitialize) {
+            const persistedDelegations = await this.delegationManager.loadAll();
+            for (const delegation of persistedDelegations) {
+                await this.transport.release(delegation.id).catch(() => { });
+                await this.environmentManager.release(delegation.id);
+                await this.snapshotManager.cleanupDelegation(delegation.id);
+                await this.delegationManager.delete(delegation.id).catch(() => { });
+            }
+            return;
+        }
+        const persistedDelegations = await this.delegationManager.loadAll();
+        const knownIds = new Set(persistedDelegations.map(d => d.id));
+        await this.environmentManager.cleanupStale(knownIds);
+        await this.snapshotManager.cleanupStale(knownIds);
+        for (const delegation of persistedDelegations) {
+            this.delegations.set(delegation.id, delegation);
+            this.stateMachines.set(delegation.id, new DelegationStateMachine(delegation.state));
+        }
+        for (const delegation of persistedDelegations) {
+            if (isTerminalState(delegation.state))
+                continue;
+            console.log(`[AWCP:Delegator] Auto-resuming delegation ${delegation.id} (state=${delegation.state})`);
+            try {
+                await this.delegate({
+                    existingId: delegation.id,
+                    executorUrl: delegation.peerUrl,
+                    environment: delegation.environment,
+                    task: delegation.task,
+                });
+            }
+            catch (error) {
+                console.error(`[AWCP:Delegator] Failed to resume ${delegation.id}:`, error instanceof Error ? error.message : error);
+            }
+        }
+    }
+    async shutdown() {
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+            this.cleanupTimer = undefined;
+        }
+        await this.transport.shutdown?.();
+        this.delegations.clear();
+        this.stateMachines.clear();
+    }
     async delegate(params) {
-        const delegationId = generateDelegationId();
+        const isResume = !!params.existingId;
+        const delegationId = params.existingId ?? generateDelegationId();
+        if (isResume) {
+            const existing = this.delegations.get(delegationId);
+            if (!existing) {
+                throw new Error(`Cannot resume unknown delegation: ${delegationId}` +
+                    ` (known=[${Array.from(this.delegations.keys()).join(',')}])`);
+            }
+            if (isTerminalState(existing.state)) {
+                throw new Error(`Cannot resume terminal delegation: ${delegationId} (state=${existing.state})`);
+            }
+            await this.transport.detach(delegationId).catch(() => { });
+            this.stateMachines.set(delegationId, new DelegationStateMachine());
+        }
         for (const resource of params.environment.resources) {
             const sourcePath = await this.validateAndNormalizePath(resource.source, delegationId);
             resource.source = sourcePath;
-            const admissionResult = await this.admissionController.check(sourcePath);
-            if (!admissionResult.allowed) {
-                throw new WorkspaceTooLargeError(admissionResult.stats ?? {}, admissionResult.hint, delegationId);
-            }
+            await this.admissionController.check(sourcePath, delegationId);
+            await this.config.hooks.onAdmissionCheck?.(sourcePath);
         }
-        const ttlSeconds = params.ttlSeconds ?? this.config.defaults.ttlSeconds;
-        const accessMode = params.accessMode ?? this.config.defaults.accessMode;
-        const snapshotMode = params.snapshotMode ?? this.config.snapshot.mode;
-        const delegation = createDelegation({
-            id: delegationId,
-            peerUrl: params.executorUrl,
-            environment: params.environment,
-            task: params.task,
-            leaseConfig: { ttlSeconds, accessMode },
-        });
-        delegation.snapshotPolicy = {
-            mode: snapshotMode,
-            retentionMs: this.config.snapshot.retentionMs,
-            maxSnapshots: this.config.snapshot.maxSnapshots,
-        };
-        const { envRoot } = await this.environmentBuilder.build(delegationId, params.environment);
-        delegation.exportPath = envRoot;
-        const stateMachine = new DelegationStateMachine();
-        this.delegations.set(delegationId, delegation);
-        this.stateMachines.set(delegationId, stateMachine);
-        this.executorUrls.set(delegationId, params.executorUrl);
-        const inviteMessage = {
-            version: PROTOCOL_VERSION,
-            type: 'INVITE',
-            delegationId,
-            task: params.task,
-            lease: { ttlSeconds, accessMode },
-            environment: {
-                resources: params.environment.resources.map(r => ({
-                    name: r.name,
-                    type: r.type,
-                    mode: r.mode,
-                })),
-            },
-            requirements: {
-                transport: this.transport.type,
-            },
-            ...(params.auth && { auth: params.auth }),
-        };
-        this.transitionState(delegationId, { type: 'SEND_INVITE', message: inviteMessage });
+        const ttlSeconds = params.ttlSeconds ?? this.config.delegation.lease.ttlSeconds;
+        const accessMode = params.accessMode ?? this.config.delegation.lease.accessMode;
+        const snapshotMode = params.snapshotMode ?? this.config.delegation.snapshot.mode;
+        const retentionMs = params.retentionMs ?? this.config.delegation.retentionMs;
         try {
+            const { envRoot } = await this.environmentManager.build(delegationId, params.environment);
+            if (isResume) {
+                const delegation = this.delegations.get(delegationId);
+                delegation.state = 'created';
+                delegation.exportPath = envRoot;
+            }
+            else {
+                const delegation = createDelegation({
+                    id: delegationId,
+                    peerUrl: params.executorUrl,
+                    environment: params.environment,
+                    task: params.task,
+                    leaseConfig: { ttlSeconds, accessMode },
+                    retentionMs,
+                    snapshotPolicy: {
+                        mode: snapshotMode,
+                        maxSnapshots: this.config.delegation.snapshot.maxSnapshots,
+                    },
+                    exportPath: envRoot,
+                });
+                this.delegations.set(delegationId, delegation);
+                this.stateMachines.set(delegationId, new DelegationStateMachine());
+            }
+            const inviteMessage = {
+                version: PROTOCOL_VERSION,
+                type: 'INVITE',
+                delegationId,
+                task: params.task,
+                lease: { ttlSeconds, accessMode },
+                retentionMs,
+                environment: {
+                    resources: params.environment.resources.map(r => ({
+                        name: r.name,
+                        type: r.type,
+                        mode: r.mode,
+                    })),
+                },
+                requirements: {
+                    transport: this.transport.type,
+                },
+                ...(params.auth && { auth: params.auth }),
+            };
+            this.transitionState(delegationId, { type: 'SEND_INVITE', message: inviteMessage });
             const response = await this.executorClient.sendInvite(params.executorUrl, inviteMessage);
             if (response.type === 'ERROR') {
                 await this.handleError(response);
                 throw new AwcpError(response.code, response.message, response.hint, delegationId);
             }
             await this.handleAccept(response);
-            this.config.hooks.onDelegationCreated?.(delegation);
+            this.config.hooks.onDelegationCreated?.(this.delegations.get(delegationId));
             return delegationId;
         }
         catch (error) {
-            await this.cleanup(delegationId);
+            if (isResume) {
+                await this.transport.detach(delegationId).catch(() => { });
+                await this.environmentManager.release(delegationId);
+            }
+            else {
+                this.delegations.delete(delegationId);
+                this.stateMachines.delete(delegationId);
+                await this.transport.release(delegationId).catch(() => { });
+                await this.environmentManager.release(delegationId);
+                await this.delegationManager.delete(delegationId).catch(() => { });
+            }
             throw error;
         }
     }
     async handleAccept(message) {
         const delegation = this.delegations.get(message.delegationId);
         if (!delegation) {
-            console.warn(`[AWCP:Delegator] Unknown delegation for ACCEPT: ${message.delegationId}`);
-            return;
+            throw new Error(`Unknown delegation for ACCEPT: ${message.delegationId}` +
+                ` (known=[${Array.from(this.delegations.keys()).join(',')}])`);
+        }
+        this.transitionState(message.delegationId, { type: 'RECEIVE_ACCEPT', message });
+        delegation.executorWorkDir = message.executorWorkDir;
+        delegation.executorConstraints = message.executorConstraints;
+        delegation.executorRetentionMs = message.retentionMs;
+        let stream;
+        try {
+            const handle = await this.transport.prepare({
+                delegationId: delegation.id,
+                exportPath: delegation.exportPath,
+                ttlSeconds: delegation.leaseConfig.ttlSeconds,
+            });
+            const expiresAt = new Date(Date.now() + delegation.leaseConfig.ttlSeconds * 1000).toISOString();
+            const startMessage = {
+                version: PROTOCOL_VERSION,
+                type: 'START',
+                delegationId: delegation.id,
+                lease: {
+                    expiresAt,
+                    accessMode: delegation.leaseConfig.accessMode,
+                },
+                transportHandle: handle,
+            };
+            stream = await this.executorClient.connectTaskEvents(delegation.peerUrl, delegation.id);
+            this.transitionState(delegation.id, { type: 'SEND_START', message: startMessage });
+            delegation.activeLease = startMessage.lease;
+            await this.executorClient.sendStart(delegation.peerUrl, startMessage);
         }
-        const executorUrl = this.executorUrls.get(message.delegationId);
-        const result = this.transitionState(message.delegationId, { type: 'RECEIVE_ACCEPT', message });
-        if (!result.success) {
-            console.error(`[AWCP:Delegator] State transition failed: ${result.error}`);
-            return;
+        catch (error) {
+            stream?.abort();
+            await this.transport.detach(delegation.id).catch(() => { });
+            throw error;
         }
-        const updated = applyMessageToDelegation(delegation, message);
-        this.delegations.set(delegation.id, updated);
-        const { workDirInfo } = await this.transport.prepare({
-            delegationId: delegation.id,
-            exportPath: updated.exportPath,
-            ttlSeconds: delegation.leaseConfig.ttlSeconds,
+        this.config.hooks.onDelegationStarted?.(delegation);
+        console.log(`[AWCP:Delegator] START sent for ${delegation.id}, consuming SSE events...`);
+        this.consumeTaskEvents(delegation.id, stream).catch((error) => {
+            console.error(`[AWCP:Delegator] SSE error for ${delegation.id}:`, error);
         });
-        const expiresAt = new Date(Date.now() + delegation.leaseConfig.ttlSeconds * 1000).toISOString();
-        const startMessage = {
-            version: PROTOCOL_VERSION,
-            type: 'START',
-            delegationId: delegation.id,
-            lease: {
-                expiresAt,
-                accessMode: delegation.leaseConfig.accessMode,
-            },
-            workDir: workDirInfo,
+    }
+    async handleDone(message) {
+        const delegation = this.delegations.get(message.delegationId);
+        if (!delegation) {
+            throw new Error(`Unknown delegation for DONE: ${message.delegationId}` +
+                ` (known=[${Array.from(this.delegations.keys()).join(',')}])`);
+        }
+        const stateMachine = this.stateMachines.get(message.delegationId);
+        if (stateMachine.getState() === 'started') {
+            this.transitionState(message.delegationId, { type: 'SETUP_COMPLETE' });
+        }
+        this.transitionState(message.delegationId, { type: 'RECEIVE_DONE', message });
+        delegation.result = {
+            summary: message.finalSummary,
+            highlights: message.highlights,
         };
-        this.transitionState(delegation.id, { type: 'SEND_START', message: startMessage });
-        updated.activeLease = startMessage.lease;
-        this.delegations.set(delegation.id, updated);
-        await this.executorClient.sendStart(executorUrl, startMessage);
-        this.config.hooks.onDelegationStarted?.(updated);
-        this.subscribeToTaskEvents(delegation.id, executorUrl);
+        await this.persistDelegation(delegation.id);
+        await this.transport.detach(delegation.id).catch(() => { });
+        await this.environmentManager.release(delegation.id);
+        this.config.hooks.onDelegationCompleted?.(delegation);
     }
-    async subscribeToTaskEvents(delegationId, executorUrl) {
+    async handleError(message) {
+        const delegation = this.delegations.get(message.delegationId);
+        if (!delegation) {
+            throw new Error(`Unknown delegation for ERROR: ${message.delegationId}` +
+                ` (known=[${Array.from(this.delegations.keys()).join(',')}])`);
+        }
+        console.log(`[AWCP:Delegator] Processing error for ${message.delegationId}` +
+            ` (state=${delegation.state}): ${message.code} - ${message.message}`);
+        this.transitionState(message.delegationId, { type: 'RECEIVE_ERROR', message });
+        delegation.error = {
+            code: message.code,
+            message: message.message,
+            hint: message.hint,
+        };
+        await this.persistDelegation(delegation.id);
+        const error = new AwcpError(message.code, message.message, message.hint, delegation.id);
+        this.config.hooks.onError?.(delegation.id, error);
+    }
+    async consumeTaskEvents(delegationId, stream) {
         try {
-            console.log(`[AWCP:Delegator] Subscribing to SSE for ${delegationId}`);
-            for await (const event of this.executorClient.subscribeTask(executorUrl, delegationId)) {
-                console.log(`[AWCP:Delegator] SSE event for ${delegationId}: ${event.type}`);
+            for await (const event of stream.events) {
+                console.log(`[AWCP:Delegator] SSE event for ${delegationId}: type=${event.type}`);
                 await this.handleTaskEvent(delegationId, event);
                 if (event.type === 'done' || event.type === 'error') {
+                    console.log(`[AWCP:Delegator] SSE stream ended for ${delegationId} (terminal event: ${event.type})`);
                     break;
                 }
             }
         }
         catch (error) {
-            console.error(`[AWCP:Delegator] SSE subscription error for ${delegationId}:`, error);
-            const delegation = this.delegations.get(delegationId);
-            if (delegation && !['completed', 'error', 'cancelled'].includes(delegation.state)) {
-                delegation.state = 'error';
-                delegation.error = {
+            console.error(`[AWCP:Delegator] SSE connection lost for ${delegationId}:`, error instanceof Error ? error.message : error);
+            const current = this.delegations.get(delegationId);
+            if (current && !isTerminalState(current.state)) {
+                console.error(`[AWCP:Delegator] Marking ${delegationId} as error (was ${current.state})`);
+                current.state = 'error';
+                current.error = {
                     code: 'SSE_FAILED',
-                    message: error instanceof Error ? error.message : 'SSE subscription failed',
+                    message: `SSE connection lost: ${error instanceof Error ? error.message : 'unknown error'}`,
                 };
-                this.delegations.set(delegationId, delegation);
+                current.updatedAt = new Date().toISOString();
+                await this.persistDelegation(delegationId);
             }
         }
     }
@@ -181,10 +303,7 @@ export class DelegatorService {
             await this.handleSnapshotEvent(delegationId, event);
         }
         if (event.type === 'done') {
-            const executorUrl = this.executorUrls.get(delegationId);
-            if (executorUrl) {
-                await this.executorClient.acknowledgeResult(executorUrl, delegationId).catch(() => { });
-            }
+            await this.executorClient.acknowledgeResult(delegation.peerUrl, delegationId).catch(() => { });
             const doneMessage = {
                 version: PROTOCOL_VERSION,
                 type: 'DONE',
@@ -195,6 +314,8 @@ export class DelegatorService {
             await this.handleDone(doneMessage);
         }
         if (event.type === 'error') {
+            console.error(`[AWCP:Delegator] Executor reported error for ${delegationId}:` +
+                ` code=${event.code}, message=${event.message}`);
             const errorMessage = {
                 version: PROTOCOL_VERSION,
                 type: 'ERROR',
@@ -207,137 +328,24 @@ export class DelegatorService {
         }
     }
     async handleSnapshotEvent(delegationId, event) {
-        // liveSync transports don't produce snapshots
-        if (this.transport.capabilities.liveSync)
-            return;
-        const delegation = this.delegations.get(delegationId);
-        if (!delegation)
-            return;
-        const policy = delegation.snapshotPolicy ?? {
-            mode: this.config.snapshot.mode,
-            retentionMs: this.config.snapshot.retentionMs,
-            maxSnapshots: this.config.snapshot.maxSnapshots,
-        };
-        if (!delegation.snapshots) {
-            delegation.snapshots = [];
-        }
-        const snapshot = {
-            id: event.snapshotId,
-            delegationId,
-            summary: event.summary,
-            highlights: event.highlights,
-            status: 'pending',
-            metadata: event.metadata,
-            recommended: event.recommended,
-            createdAt: new Date().toISOString(),
-        };
-        if (policy.mode === 'auto') {
-            await this.applySnapshotToWorkspace(delegationId, event.snapshotBase64);
-            snapshot.status = 'applied';
-            snapshot.appliedAt = new Date().toISOString();
-            delegation.appliedSnapshotId = event.snapshotId;
-        }
-        else if (policy.mode === 'staged') {
-            const localPath = await this.snapshotStore.save(delegationId, event.snapshotId, event.snapshotBase64, { summary: event.summary, highlights: event.highlights, ...event.metadata });
-            snapshot.localPath = localPath;
-        }
-        else {
-            snapshot.status = 'discarded';
-        }
-        delegation.snapshots.push(snapshot);
-        delegation.updatedAt = new Date().toISOString();
-        this.config.hooks.onSnapshotReceived?.(delegation, snapshot);
-    }
-    async applySnapshotToWorkspace(delegationId, snapshotData) {
         const delegation = this.delegations.get(delegationId);
         if (!delegation)
             return;
-        if (!this.environmentBuilder.get(delegationId))
-            return;
-        const rwResources = delegation.environment.resources.filter(r => r.mode === 'rw');
-        if (rwResources.length === 0)
-            return;
-        try {
-            if (this.transport.applySnapshot) {
-                await this.transport.applySnapshot({
-                    delegationId,
-                    snapshotData,
-                    resources: rwResources.map(r => ({ name: r.name, source: r.source, mode: r.mode })),
-                });
-                console.log(`[AWCP:Delegator] Applied snapshot for ${delegationId}`);
-            }
-        }
-        catch (error) {
-            console.error(`[AWCP:Delegator] Failed to apply snapshot for ${delegationId}:`, error);
-        }
-    }
-    async handleDone(message) {
-        const delegation = this.delegations.get(message.delegationId);
-        if (!delegation) {
-            console.warn(`[AWCP:Delegator] Unknown delegation for DONE: ${message.delegationId}`);
-            return;
-        }
-        const stateMachine = this.stateMachines.get(message.delegationId);
-        if (stateMachine.getState() === 'started') {
-            this.transitionState(message.delegationId, { type: 'SETUP_COMPLETE' });
-        }
-        const result = this.transitionState(message.delegationId, { type: 'RECEIVE_DONE', message });
-        if (!result.success) {
-            console.error(`[AWCP:Delegator] State transition failed: ${result.error}`);
-            return;
-        }
-        const updated = applyMessageToDelegation(delegation, message);
-        this.delegations.set(delegation.id, updated);
-        // liveSync transports: cleanup immediately (changes already synced)
-        // snapshot transports: cleanup based on policy
-        const shouldCleanupNow = this.transport.capabilities.liveSync
-            || this.config.snapshot.mode === 'auto'
-            || this.shouldCleanup(delegation);
-        if (shouldCleanupNow) {
-            await this.cleanup(delegation.id);
-        }
-        this.config.hooks.onDelegationCompleted?.(updated);
-    }
-    async handleError(message) {
-        const delegation = this.delegations.get(message.delegationId);
-        if (!delegation) {
-            console.warn(`[AWCP:Delegator] Unknown delegation for ERROR: ${message.delegationId}`);
+        const snapshot = await this.snapshotManager.receive(delegation, event);
+        if (!snapshot)
             return;
-        }
-        this.transitionState(message.delegationId, { type: 'RECEIVE_ERROR', message });
-        const updated = applyMessageToDelegation(delegation, message);
-        this.delegations.set(delegation.id, updated);
-        await this.cleanup(delegation.id);
-        const error = new AwcpError(message.code, message.message, message.hint, delegation.id);
-        this.config.hooks.onError?.(delegation.id, error);
-    }
-    async handleMessage(message) {
-        switch (message.type) {
-            case 'ACCEPT':
-                await this.handleAccept(message);
-                break;
-            case 'DONE':
-                await this.handleDone(message);
-                break;
-            case 'ERROR':
-                await this.handleError(message);
-                break;
-            default:
-                console.warn(`[AWCP:Delegator] Unexpected message type: ${message.type}`);
-        }
+        await this.persistDelegation(delegationId);
+        this.config.hooks.onSnapshotReceived?.(delegation, snapshot);
     }
     async cancel(delegationId) {
         const delegation = this.delegations.get(delegationId);
         if (!delegation) {
             throw new Error(`Unknown delegation: ${delegationId}`);
         }
-        const executorUrl = this.executorUrls.get(delegationId);
-        const result = this.transitionState(delegationId, { type: 'CANCEL' });
-        if (!result.success) {
-            throw new Error(`Cannot cancel delegation in state ${delegation.state}`);
-        }
-        await this.executorClient.sendCancel(executorUrl, delegationId).catch(console.error);
-        await this.cleanup(delegationId);
+        this.transitionState(delegationId, { type: 'CANCEL' });
+        await this.persistDelegation(delegationId);
+        await this.executorClient.sendCancel(delegation.peerUrl, delegationId).catch(console.error);
+        await this.transport.detach(delegationId).catch(() => { });
     }
     getDelegation(delegationId) {
         return this.delegations.get(delegationId);
@@ -352,55 +360,16 @@ export class DelegatorService {
         const delegation = this.delegations.get(delegationId);
         if (!delegation)
             throw new Error(`Unknown delegation: ${delegationId}`);
-        const snapshot = delegation.snapshots?.find(s => s.id === snapshotId);
-        if (!snapshot)
-            throw new Error(`Snapshot not found: ${snapshotId}`);
-        if (snapshot.status === 'applied')
-            throw new Error(`Snapshot already applied: ${snapshotId}`);
-        const snapshotBuffer = await this.snapshotStore.load(delegationId, snapshotId);
-        const snapshotBase64 = snapshotBuffer.toString('base64');
-        await this.applySnapshotToWorkspace(delegationId, snapshotBase64);
-        snapshot.status = 'applied';
-        snapshot.appliedAt = new Date().toISOString();
-        delegation.appliedSnapshotId = snapshotId;
-        delegation.updatedAt = new Date().toISOString();
+        const snapshot = await this.snapshotManager.apply(delegation, snapshotId);
+        await this.persistDelegation(delegationId);
         this.config.hooks.onSnapshotApplied?.(delegation, snapshot);
-        if (this.shouldCleanup(delegation)) {
-            await this.cleanup(delegationId);
-        }
     }
     async discardSnapshot(delegationId, snapshotId) {
         const delegation = this.delegations.get(delegationId);
         if (!delegation)
             throw new Error(`Unknown delegation: ${delegationId}`);
-        const snapshot = delegation.snapshots?.find(s => s.id === snapshotId);
-        if (!snapshot)
-            throw new Error(`Snapshot not found: ${snapshotId}`);
-        await this.snapshotStore.delete(delegationId, snapshotId);
-        snapshot.status = 'discarded';
-        snapshot.localPath = undefined;
-        delegation.updatedAt = new Date().toISOString();
-        if (this.shouldCleanup(delegation)) {
-            await this.cleanup(delegationId);
-        }
-    }
-    async waitForCompletion(delegationId, timeoutMs = 60000) {
-        const startTime = Date.now();
-        while (Date.now() - startTime < timeoutMs) {
-            const delegation = this.delegations.get(delegationId);
-            if (!delegation) {
-                throw new Error(`Unknown delegation: ${delegationId}`);
-            }
-            const stateMachine = this.stateMachines.get(delegationId);
-            if (stateMachine.isTerminal()) {
-                if (delegation.error) {
-                    throw new AwcpError(delegation.error.code, delegation.error.message, delegation.error.hint, delegationId);
-                }
-                return delegation;
-            }
-            await new Promise((resolve) => setTimeout(resolve, 100));
-        }
-        throw new Error('Timeout waiting for delegation to complete');
+        await this.snapshotManager.discard(delegation, snapshotId);
+        await this.persistDelegation(delegationId);
     }
     getStatus() {
         return {
@@ -414,34 +383,26 @@ export class DelegatorService {
             })),
         };
     }
-    stop() {
-        if (this.cleanupTimer) {
-            clearInterval(this.cleanupTimer);
-            this.cleanupTimer = undefined;
-        }
-    }
-    shouldCleanup(delegation) {
-        if (!delegation.snapshots || delegation.snapshots.length === 0) {
-            return true;
+    async persistDelegation(delegationId) {
+        const delegation = this.delegations.get(delegationId);
+        if (delegation) {
+            await this.delegationManager.save(delegation);
         }
-        return delegation.snapshots.every(s => s.status !== 'pending');
-    }
-    async cleanup(delegationId) {
-        await this.transport.cleanup(delegationId);
-        await this.environmentBuilder.release(delegationId);
-        await this.snapshotStore.cleanupDelegation(delegationId);
-        this.executorUrls.delete(delegationId);
     }
     startCleanupTimer() {
         this.cleanupTimer = setInterval(async () => {
             const now = Date.now();
             for (const [id, delegation] of this.delegations) {
-                if (!['completed', 'error', 'cancelled'].includes(delegation.state))
+                if (!isTerminalState(delegation.state))
                     continue;
-                const policy = delegation.snapshotPolicy ?? { retentionMs: this.config.snapshot.retentionMs };
                 const updatedAt = new Date(delegation.updatedAt).getTime();
-                if (now - updatedAt > (policy.retentionMs ?? this.config.snapshot.retentionMs)) {
-                    await this.cleanup(id);
+                if (now - updatedAt > delegation.retentionMs) {
+                    await this.transport.release(id).catch(() => { });
+                    await this.environmentManager.release(id);
+                    await this.snapshotManager.cleanupDelegation(id);
+                    await this.delegationManager.delete(id).catch(() => { });
+                    this.delegations.delete(id);
+                    this.stateMachines.delete(id);
                 }
             }
         }, 60 * 1000);
@@ -450,11 +411,11 @@ export class DelegatorService {
         const sm = this.stateMachines.get(delegationId);
         const delegation = this.delegations.get(delegationId);
         const result = sm.transition(event);
-        if (result.success) {
-            delegation.state = sm.getState();
-            delegation.updatedAt = new Date().toISOString();
+        if (!result.success) {
+            throw new Error(`Cannot transition delegation ${delegationId} (${event.type}) in state '${delegation.state}': ${result.error}`);
         }
-        return result;
+        delegation.state = sm.getState();
+        delegation.updatedAt = new Date().toISOString();
     }
     async validateAndNormalizePath(localDir, delegationId) {
         const absolutePath = path.isAbsolute(localDir)